diff --git a/docs/en/reference/site-config.md b/docs/en/reference/site-config.md index 938854f85..67fd0640a 100644 --- a/docs/en/reference/site-config.md +++ b/docs/en/reference/site-config.md @@ -134,13 +134,43 @@ export default defineConfigWithTheme({ You can configure the underlying [Markdown-It](https://github.com/markdown-it/markdown-it) instance using the [markdown](#markdown) option in your VitePress config. +### Page-Level Overrides + +Some settings can be overridden for specific pages using frontmatter. + +See [Frontmatter Config](./frontmatter-config) for details. + +### Directory-Level Overrides + +Some config settings can be overridden at the directory level, allowing all pages in that directory to share settings without needing to repeat them in the frontmatter of each page. + +This is achieved by adding a file called `config.ts` (or `.js`, `.mjs`, or `.mts`) in the relevant directory. This file should export a config object using `export default`, similar to the main config file. + +Nested directories inherit settings from their parent directory, with configuration overrides being merged accordingly. + +The `defineAdditionalConfig` helper can be used to get TypeScript-powered intellisense for the available options, though as with `defineConfig` its use is optional. + +For example, for a site with multiple languages we might want a different `description` for each language. We could add `es/config.ts` with the following content: + +```ts +import { defineAdditionalConfig } from 'vitepress' + +export default defineAdditionalConfig({ + description: 'Generador de Sitios Estáticos desarrollado con Vite y Vue.' +}) +``` + +This `description` would then be used for all pages in the `es` directory. + +Alternatively, when using the built-in i18n features, the settings for a locale directory can be overridden via the `locales` setting in the main configuration file. See [Internationalization](../guide/i18n) for details. + ## Site Metadata ### title - Type: `string` - Default: `VitePress` -- Can be overridden per page via [frontmatter](./frontmatter-config#title) +- Can be overridden per page via [frontmatter](./frontmatter-config#title) or at the [directory level](#directory-level-overrides) Title for the site. When using the default theme, this will be displayed in the nav bar. @@ -161,7 +191,7 @@ The title of the page will be `Hello | My Awesome Site`. ### titleTemplate - Type: `string | boolean` -- Can be overridden per page via [frontmatter](./frontmatter-config#titletemplate) +- Can be overridden per page via [frontmatter](./frontmatter-config#titletemplate) or at the [directory level](#directory-level-overrides) Allows customizing each page's title suffix or the entire title. For example: @@ -194,7 +224,7 @@ The option can be set to `false` to disable title suffixes. - Type: `string` - Default: `A VitePress site` -- Can be overridden per page via [frontmatter](./frontmatter-config#description) +- Can be overridden per page via [frontmatter](./frontmatter-config#description) or at the [directory level](#directory-level-overrides) Description for the site. This will render as a `` tag in the page HTML. @@ -208,7 +238,7 @@ export default { - Type: `HeadConfig[]` - Default: `[]` -- Can be appended per page via [frontmatter](./frontmatter-config#head) +- Can be appended per page via [frontmatter](./frontmatter-config#head) or at the [directory level](#directory-level-overrides) Additional elements to render in the `` tag in the page HTML. The user-added tags are rendered before the closing `head` tag, after VitePress tags. @@ -320,6 +350,7 @@ export default { - Type: `string` - Default: `en-US` +- Can be overridden at the [directory level](#directory-level-overrides) The lang attribute for the site. This will render as a `` tag in the page HTML.