Site config is where you can define the global settings of the site. App config options define settings that apply to every VitePress site, regardless of what theme it is using. For example, the base directory or the title of the site.
## Config Resolution
<divclass="site-config-toc">
[[toc]]
</div>
<style>
@media (min-width: 1280px) {
.site-config-toc {
display: none;
}
}
</style>
## Overview
### Config Resolution
Place your configuration file at `.vitepress/config.js`. This is where all VitePress-specific files will be placed.
@ -34,7 +50,7 @@ export default {
}
```
## Config Intellisense
### Config Intellisense
Since VitePress ships with TypeScript typings, you can leverage your IDE's intellisense with jsdoc type hints:
@ -61,7 +77,7 @@ export default defineConfig({
VitePress also directly supports TS config files. You can use `.vitepress/config.ts` with the `defineConfig` helper as well.
## Typed Theme Config
### Typed Theme Config
By default, `defineConfig` helper leverages the theme config type from default theme:
Title for the site. This will be displayed in the nav bar. Also used as the suffix for all page titles unless `titleTemplate` is defined.
- If the option is set to `true`, the default theme will be determined by the user's preferred color scheme.
- If the option is set to `dark`, the theme will be dark by default, unless the user manually toggles it.
- If the option is set to `false`, users will not be able to toggle the theme.
```ts
export default {
title: 'VitePress'
}
```
It also injects inline script that tries to read users settings from local storage by `vitepress-theme-appearance` key and restores users preferred color mode.
### titleTemplate
- Type: `string | boolean`
The suffix for the title. For example, if you set `title` as `VitePress` and set `titleTemplate` as `My Site`, the html title becomes `VitePress | My Site`.
Set `false` to disable the feature. If the option is `undefined`, then the value of `title` option will be used.
```ts
export default {
appearance: true
title: 'VitePress',
titleTemplate: 'Vite & Vue powered static site generator'
}
```
To configure a title separator other than `|`, you can omit `title` and use the `:title` symbol in `titleTemplate`.
```ts
export default {
titleTemplate: ':title - Vitepress'
}
```
### description
- Type: `string`
- Default: `A VitePress site`
Description for the site. This will render as a `<meta>` tag in the page HTML.
```ts
export default {
description: 'A VitePress site'
}
```
@ -124,16 +170,16 @@ export default {
}
```
### description
### lang
- Type: `string`
- Default: `A VitePress site`
- Default: `en-US`
Description for the site. This will render as a `<meta>` tag in the page HTML.
The lang attribute for the site. This will render as a `<html lang="en-US">` tag in the page HTML.
```ts
export default {
description: 'A VitePress site'
lang: 'en-US'
}
```
@ -162,29 +208,57 @@ type HeadConfig =
| [string, Record<string,string>, string]
```
### ignoreDeadLinks
## Routing
- Type: `boolean | 'localhostLinks'`
### cleanUrls
- Type: `boolean`
- Default: `false`
When set to `true`, VitePress will not fail builds due to dead links. When set to `localhostLinks`, the build will fail on dead links, but won't check `localhost` links.
Allows removing trailing `.html` from URLs.
```ts
export default {
ignoreDeadLinks: true
cleanUrls: true
}
```
### lang
::: warning
Enabling this may require additional configuration on your hosting platform. For it to work, your server must serve `/foo.html` on requesting `/foo`**without a redirect**.
:::
- Type: `string`
- Default: `en-US`
### rewrites
The lang attribute for the site. This will render as a `<html lang="en-US">` tag in the page HTML.
- Type: `Record<string, string>`
Defines custom directory <-> URL mappings. See [Routing: Customize the Mappings](/guide/routing#customize-the-mappings) for more details.
```ts
export default {
lang: 'en-US'
rewrites: {
'source/:page': 'destination/:page'
}
}
```
## Theming
### appearance
- Type: `boolean | 'dark'`
- Default: `true`
Whether to enable dark mode or not.
- If the option is set to `true`, the default theme will be determined by the user's preferred color scheme.
- If the option is set to `dark`, the theme will be dark by default, unless the user manually toggles it.
- If the option is set to `false`, users will not be able to toggle the theme.
It also injects inline script that tries to read users settings from local storage by `vitepress-theme-appearance` key and restores users preferred color mode.
The build output location for the site, relative to project root (`docs` folder if you're running `vitepress build docs`).
Pass raw [Vite Config](https://vitejs.dev/config/) to internal Vite dev server / bundler.
```ts
export default {
outDir: '../public'
}
```
### vue
### cacheDir
- Type: `import('@vitejs/plugin-vue').Options`
- Type: `string`
- Default: `./.vitepress/cache`
The directory for cache files, relative to project root (`docs` folder if you're running `vitepress build docs`). See also: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir).
Pass raw [`@vitejs/plugin-vue` options](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) to the internal plugin instance.
```ts
export default {
cacheDir: './.vitepress/.vite'
}
```
## Build
### srcDir
@ -312,80 +376,59 @@ export default {
}
```
### title
### srcExclude
- Type: `string`
- Default: `VitePress`
- Default: `undefined`
Title for the site. This will be displayed in the nav bar. Also used as the suffix for all page titles unless `titleTemplate` is defined.
A [glob pattern](https://github.com/mrmlnc/fast-glob#pattern-syntax) for matching markdown files that should be excluded as source content.
```ts
export default {
title: 'VitePress'
srcExclude: ['**/README.md', '**/TODO.md']
}
```
### titleTemplate
- Type: `string | boolean`
The suffix for the title. For example, if you set `title` as `VitePress` and set `titleTemplate` as `My Site`, the html title becomes `VitePress | My Site`.
Set `false` to disable the feature. If the option is `undefined`, then the value of `title` option will be used.
### outDir
```ts
export default {
title: 'VitePress',
titleTemplate: 'Vite & Vue powered static site generator'
}
```
- Type: `string`
- Default: `./.vitepress/dist`
To configure a title separator other than `|`, you can omit `title` and use the `:title` symbol in `titleTemplate`.
The build output location for the site, relative to project root (`docs` folder if you're running `vitepress build docs`).
```ts
export default {
titleTemplate: ':title - Vitepress'
outDir: '../public'
}
```
### cleanUrls
### cacheDir
- Type: `boolean`
- Default: `false`
- Type: `string`
- Default: `./.vitepress/cache`
Allows removing trailing `.html` from URLs.
The directory for cache files, relative to project root (`docs` folder if you're running `vitepress build docs`). See also: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir).
```ts
export default {
cleanUrls: true
cacheDir: './.vitepress/.vite'
}
```
::: warning
Enabling this may require additional configuration on your hosting platform. For it to work, your server must serve `/foo.html` on requesting `/foo`**without a redirect**.
:::
### rewrites
### ignoreDeadLinks
- Type: `Record<string, string>`
- Type: `boolean | 'localhostLinks'`
- Default: `false`
Defines custom directory <-> URL mappings. See [Routing: Customize the Mappings](/guide/routing#customize-the-mappings) for more details.
When set to `true`, VitePress will not fail builds due to dead links. When set to `localhostLinks`, the build will fail on dead links, but won't check `localhost` links.
```ts
export default {
rewrites: {
'source/:page': 'destination/:page'
}
ignoreDeadLinks: true
}
```
### vite
- Type: `ViteUserConfig`
Pass raw [Vite Config](https://vitejs.dev/config/) to underlying Vite dev server / bundler.
### Build Hooks
## Build Hooks
VitePress build hooks allow you to add new functionality and behaviors to your website:
@ -394,7 +437,7 @@ VitePress build hooks allow you to add new functionality and behaviors to your w
Evan You
3 years ago