VitePress · Schema
VitePress Site Configuration
Schema for the VitePress site configuration object exported from .vitepress/config.[js|ts|mjs|mts]. Defines all settings that control site metadata, routing, theming, Markdown processing, Vite and Vue integration, and build hooks for generating static documentation sites powered by Vite and Vue.
DocumentationMarkdownOpen SourceStatic Site GeneratorViteVue
Properties
| Name | Type | Description |
|---|---|---|
| title | string | Title for the site. Displayed in the nav bar when using the default theme and used as the default suffix for all individual page titles. |
| titleTemplate | object | Suffix or template for page titles. Use ':title' as a placeholder for the page title. Set to false to disable title suffixes. |
| description | string | Description for the site rendered as a meta tag in each page's HTML. |
| head | array | Additional elements to render in the tag. Each item is a tuple of [tag, attributes] or [tag, attributes, innerHTML]. |
| lang | string | Language attribute for the site, e.g. 'en-US'. Rendered as the lang attribute of the element. |
| base | string | The base URL the site will be deployed at. Must start and end with a slash. All internal links will be prepended with this value. |
| srcDir | string | The directory where your Markdown pages are stored, relative to project root. |
| srcExclude | array | Glob patterns for Markdown files that should be excluded from being treated as content source files. |
| outDir | string | The build output location for the site, relative to project root. |
| assetsDir | string | Specify the directory to nest generated assets under. The path should be inside outDir. |
| cacheDir | string | The directory for cache files, relative to project root. |
| ignoreDeadLinks | object | When true, VitePress will not fail builds due to dead links. Can be an array of strings, RegExp patterns, or filter functions for selective ignoring. |
| lastUpdated | boolean | Whether to get the last updated timestamp for each page using Git. When enabled with the default theme, displays the last updated time on each page. |
| appearance | object | Whether to enable dark mode. true uses system preference, 'dark' defaults to dark, false disables toggle, 'force-dark' always dark, 'force-auto' always system preference. |
| metaChunk | boolean | Experimental. When true, extracts page metadata to a separate JavaScript chunk instead of inlining it in the initial HTML, reducing per-page payload size. |
| mpa | boolean | Experimental. When true, builds in MPA (Multi-Page Application) mode which ships 0kb JavaScript by default at the cost of disabling client-side navigation. |
| markdown | object | Configuration options for the Markdown-it parser and Shiki syntax highlighter. Passed directly to the internal Markdown-it instance. |
| vite | object | Raw Vite configuration passed to the internal Vite dev server and bundler. Accepts any Vite UserConfig options. |
| vue | object | Options passed to the internal @vitejs/plugin-vue instance for configuring Vue SFC compilation. |
| themeConfig | object | Theme configuration object. When using the default theme this is typed as DefaultTheme.Config. Custom themes receive this object as-is. |
| locales | object | Internationalization configuration. Keys are locale paths (or 'root' for the default locale) and values are locale-specific config objects. |
| buildEnd | object | Build hook called after SSG build completes but before the CLI process exits. Receives the SiteConfig. (Function — represented as object in JSON Schema.) |
| postRender | object | Build hook called when SSG rendering is done. Allows handling teleports content during SSG. (Function — represented as object in JSON Schema.) |
| transformHead | object | Build hook to transform the before generating each page. Returns additional HeadConfig entries to merge with existing ones. (Function — represented as object in JSON Schema.) |
| transformHtml | object | Build hook to transform the HTML content of each page before saving to disk. (Function — represented as object in JSON Schema.) |
| transformPageData | object | Hook to transform the PageData of each page. Can mutate pageData directly or return a partial object to merge. (Function — represented as object in JSON Schema.) |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://apievangelist.com/schemas/vitepress/vitepress-config.json",
"title": "VitePress Site Configuration",
"description": "Schema for the VitePress site configuration object exported from .vitepress/config.[js|ts|mjs|mts]. Defines all settings that control site metadata, routing, theming, Markdown processing, Vite and Vue integration, and build hooks for generating static documentation sites powered by Vite and Vue.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Title for the site. Displayed in the nav bar when using the default theme and used as the default suffix for all individual page titles.",
"default": "VitePress"
},
"titleTemplate": {
"oneOf": [
{ "type": "string" },
{ "type": "boolean" }
],
"description": "Suffix or template for page titles. Use ':title' as a placeholder for the page title. Set to false to disable title suffixes."
},
"description": {
"type": "string",
"description": "Description for the site rendered as a meta tag in each page's HTML.",
"default": "A VitePress site"
},
"head": {
"type": "array",
"description": "Additional elements to render in the <head> tag. Each item is a tuple of [tag, attributes] or [tag, attributes, innerHTML].",
"items": {
"$ref": "#/$defs/HeadConfig"
},
"default": []
},
"lang": {
"type": "string",
"description": "Language attribute for the site, e.g. 'en-US'. Rendered as the lang attribute of the <html> element.",
"default": "en-US"
},
"base": {
"type": "string",
"description": "The base URL the site will be deployed at. Must start and end with a slash. All internal links will be prepended with this value.",
"default": "/",
"pattern": "^/"
},
"srcDir": {
"type": "string",
"description": "The directory where your Markdown pages are stored, relative to project root.",
"default": "."
},
"srcExclude": {
"type": "array",
"description": "Glob patterns for Markdown files that should be excluded from being treated as content source files.",
"items": {
"type": "string",
"description": "A glob pattern string."
}
},
"outDir": {
"type": "string",
"description": "The build output location for the site, relative to project root.",
"default": "./.vitepress/dist"
},
"assetsDir": {
"type": "string",
"description": "Specify the directory to nest generated assets under. The path should be inside outDir.",
"default": "assets"
},
"cacheDir": {
"type": "string",
"description": "The directory for cache files, relative to project root.",
"default": "./.vitepress/cache"
},
"ignoreDeadLinks": {
"description": "When true, VitePress will not fail builds due to dead links. Can be an array of strings, RegExp patterns, or filter functions for selective ignoring.",
"oneOf": [
{ "type": "boolean" },
{ "type": "string", "enum": ["localhostLinks"] },
{
"type": "array",
"items": {
"oneOf": [
{ "type": "string" },
{ "type": "object", "description": "A RegExp pattern or custom filter function (represented as object in JSON Schema)." }
]
}
}
],
"default": false
},
"lastUpdated": {
"type": "boolean",
"description": "Whether to get the last updated timestamp for each page using Git. When enabled with the default theme, displays the last updated time on each page.",
"default": false
},
"appearance": {
"description": "Whether to enable dark mode. true uses system preference, 'dark' defaults to dark, false disables toggle, 'force-dark' always dark, 'force-auto' always system preference.",
"oneOf": [
{ "type": "boolean" },
{
"type": "string",
"enum": ["dark", "force-dark", "force-auto"]
}
],
"default": true
},
"metaChunk": {
"type": "boolean",
"description": "Experimental. When true, extracts page metadata to a separate JavaScript chunk instead of inlining it in the initial HTML, reducing per-page payload size.",
"default": false
},
"mpa": {
"type": "boolean",
"description": "Experimental. When true, builds in MPA (Multi-Page Application) mode which ships 0kb JavaScript by default at the cost of disabling client-side navigation.",
"default": false
},
"markdown": {
"type": "object",
"description": "Configuration options for the Markdown-it parser and Shiki syntax highlighter. Passed directly to the internal Markdown-it instance.",
"additionalProperties": true
},
"vite": {
"type": "object",
"description": "Raw Vite configuration passed to the internal Vite dev server and bundler. Accepts any Vite UserConfig options.",
"additionalProperties": true
},
"vue": {
"type": "object",
"description": "Options passed to the internal @vitejs/plugin-vue instance for configuring Vue SFC compilation.",
"additionalProperties": true
},
"themeConfig": {
"$ref": "#/$defs/DefaultThemeConfig",
"description": "Theme configuration object. When using the default theme this is typed as DefaultTheme.Config. Custom themes receive this object as-is."
},
"locales": {
"type": "object",
"description": "Internationalization configuration. Keys are locale paths (or 'root' for the default locale) and values are locale-specific config objects.",
"additionalProperties": {
"$ref": "#/$defs/LocaleConfig"
}
},
"buildEnd": {
"type": "object",
"description": "Build hook called after SSG build completes but before the CLI process exits. Receives the SiteConfig. (Function — represented as object in JSON Schema.)"
},
"postRender": {
"type": "object",
"description": "Build hook called when SSG rendering is done. Allows handling teleports content during SSG. (Function — represented as object in JSON Schema.)"
},
"transformHead": {
"type": "object",
"description": "Build hook to transform the <head> before generating each page. Returns additional HeadConfig entries to merge with existing ones. (Function — represented as object in JSON Schema.)"
},
"transformHtml": {
"type": "object",
"description": "Build hook to transform the HTML content of each page before saving to disk. (Function — represented as object in JSON Schema.)"
},
"transformPageData": {
"type": "object",
"description": "Hook to transform the PageData of each page. Can mutate pageData directly or return a partial object to merge. (Function — represented as object in JSON Schema.)"
}
},
"$defs": {
"HeadConfig": {
"description": "An HTML head element represented as a tuple. Either [tag, attributes] or [tag, attributes, innerHTML].",
"type": "array",
"minItems": 2,
"maxItems": 3,
"items": [
{
"type": "string",
"description": "The HTML tag name, e.g. 'meta', 'link', 'script'."
},
{
"type": "object",
"description": "Attribute key-value pairs for the HTML element.",
"additionalProperties": { "type": "string" }
},
{
"type": "string",
"description": "Optional innerHTML for the element."
}
]
},
"LocaleConfig": {
"type": "object",
"description": "Per-locale configuration object allowing overrides of site-level config and theme config for a specific language.",
"properties": {
"label": {
"type": "string",
"description": "The label for this locale displayed in the language selector."
},
"lang": {
"type": "string",
"description": "The lang attribute for this locale, e.g. 'en-US', 'zh-CN'."
},
"title": {
"type": "string",
"description": "Override for the site title in this locale."
},
"description": {
"type": "string",
"description": "Override for the site description in this locale."
},
"themeConfig": {
"$ref": "#/$defs/DefaultThemeConfig"
},
"link": {
"type": "string",
"description": "The link used in the language selector for this locale."
}
}
},
"DefaultThemeConfig": {
"type": "object",
"description": "Configuration for VitePress default theme. Controls navigation, sidebar, search, social links, footer, and other UI elements.",
"properties": {
"logo": {
"description": "Logo displayed in the nav bar. Can be a path string or an object with light/dark variants.",
"oneOf": [
{ "type": "string" },
{
"type": "object",
"properties": {
"src": { "type": "string", "description": "Path to the logo image." },
"alt": { "type": "string", "description": "Alt text for the logo." },
"light": { "type": "string", "description": "Path to the light mode logo." },
"dark": { "type": "string", "description": "Path to the dark mode logo." }
}
}
]
},
"siteTitle": {
"description": "Override the site title displayed in the nav bar. Set to false to hide the title.",
"oneOf": [
{ "type": "string" },
{ "type": "boolean", "enum": [false] }
]
},
"nav": {
"type": "array",
"description": "Navigation bar items displayed in the top nav.",
"items": { "$ref": "#/$defs/NavItem" }
},
"sidebar": {
"description": "Sidebar navigation configuration. Can be a flat array of sidebar items or a multi-sidebar object keyed by path.",
"oneOf": [
{
"type": "array",
"items": { "$ref": "#/$defs/SidebarItem" }
},
{
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "array",
"items": { "$ref": "#/$defs/SidebarItem" }
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": { "$ref": "#/$defs/SidebarItem" }
},
"base": { "type": "string", "description": "Base path prefix for all sidebar items in this group." }
}
}
]
}
}
]
},
"aside": {
"description": "Location of the aside (table of contents) component. true=right, 'left'=left, false=hidden.",
"oneOf": [
{ "type": "boolean" },
{ "type": "string", "enum": ["left"] }
],
"default": true
},
"outline": {
"description": "Which header levels to display in the page outline. Can be a number, tuple range, 'deep' (all), or false to hide.",
"oneOf": [
{ "type": "number", "minimum": 1, "maximum": 6 },
{
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": { "type": "number", "minimum": 1, "maximum": 6 }
},
{ "type": "string", "enum": ["deep"] },
{ "type": "boolean", "enum": [false] }
],
"default": 2
},
"socialLinks": {
"type": "array",
"description": "Social media links displayed in the nav bar.",
"items": { "$ref": "#/$defs/SocialLink" }
},
"footer": {
"$ref": "#/$defs/Footer",
"description": "Footer configuration shown at the bottom of the page."
},
"editLink": {
"$ref": "#/$defs/EditLink",
"description": "Edit link configuration for linking to the source file in a repository."
},
"lastUpdatedText": {
"type": "string",
"description": "Label text for the last updated timestamp displayed at the bottom of pages.",
"default": "Last updated"
},
"search": {
"$ref": "#/$defs/SearchConfig",
"description": "Search configuration. Supports built-in local search or Algolia DocSearch."
},
"carbonAds": {
"$ref": "#/$defs/CarbonAdsConfig",
"description": "Carbon Ads configuration for displaying ads in the sidebar."
},
"i18nRouting": {
"type": "boolean",
"description": "When false, disables automatic locale-based URL routing (e.g., /zh/foo instead of /foo)."
},
"notFound": {
"type": "object",
"description": "Customization for the 404 Not Found page.",
"properties": {
"title": { "type": "string", "description": "Title text for the 404 page." },
"quote": { "type": "string", "description": "Quote text displayed on the 404 page." },
"linkLabel": { "type": "string", "description": "Label for the home link on the 404 page." },
"linkText": { "type": "string", "description": "Text for the home link button on the 404 page." }
}
}
},
"additionalProperties": true
},
"NavItem": {
"type": "object",
"description": "A navigation bar item, either a link or a dropdown menu.",
"properties": {
"text": { "type": "string", "description": "Display text for the nav item." },
"link": { "type": "string", "description": "URL for the nav link." },
"items": {
"type": "array",
"description": "Dropdown items for a nav group.",
"items": { "$ref": "#/$defs/NavItem" }
},
"activeMatch": { "type": "string", "description": "RegExp string for matching the active route." },
"target": { "type": "string", "description": "HTML target attribute for the link." },
"rel": { "type": "string", "description": "HTML rel attribute for the link." },
"noIcon": { "type": "boolean", "description": "When true, suppresses the external link icon." }
}
},
"SidebarItem": {
"type": "object",
"description": "A sidebar navigation item, which can be a link, a section header, or a collapsible group.",
"properties": {
"text": { "type": "string", "description": "Display text for the sidebar item." },
"link": { "type": "string", "description": "URL for this sidebar item." },
"items": {
"type": "array",
"description": "Child sidebar items for a group.",
"items": { "$ref": "#/$defs/SidebarItem" }
},
"collapsed": {
"type": "boolean",
"description": "Whether the group is collapsible. If omitted the group is not collapsible. true=collapsible and initially collapsed, false=collapsible but initially expanded."
},
"base": { "type": "string", "description": "Base path prefix for all child items." },
"docFooterText": { "type": "string", "description": "Custom text for the prev/next footer when this item is active." },
"rel": { "type": "string", "description": "HTML rel attribute for the link." },
"target": { "type": "string", "description": "HTML target attribute for the link." }
}
},
"SocialLink": {
"type": "object",
"description": "A social media link displayed as an icon in the nav bar.",
"required": ["icon", "link"],
"properties": {
"icon": {
"description": "Icon identifier or SVG string. Supported values include 'github', 'twitter', 'discord', 'facebook', 'instagram', 'linkedin', 'mastodon', 'npm', 'slack', 'youtube', 'x' or an object with an svg property.",
"oneOf": [
{
"type": "string",
"enum": ["github", "twitter", "discord", "facebook", "instagram", "linkedin", "mastodon", "npm", "slack", "youtube", "x", "bluesky"]
},
{
"type": "object",
"required": ["svg"],
"properties": {
"svg": { "type": "string", "description": "Raw SVG string for a custom icon." }
}
}
]
},
"link": { "type": "string", "format": "uri", "description": "URL for the social link." },
"ariaLabel": { "type": "string", "description": "Accessibility label for the social link icon." }
}
},
"Footer": {
"type": "object",
"description": "Footer configuration displayed at the bottom of pages in the default theme.",
"properties": {
"message": { "type": "string", "description": "Footer message text (supports HTML)." },
"copyright": { "type": "string", "description": "Copyright notice text (supports HTML)." }
}
},
"EditLink": {
"type": "object",
"description": "Configuration for the 'Edit this page' link pointing to the page source in a repository.",
"required": ["pattern"],
"properties": {
"pattern": {
"type": "string",
"description": "URL pattern for the edit link. Use ':path' as a placeholder for the page file path, e.g. 'https://github.com/org/repo/edit/main/docs/:path'."
},
"text": {
"type": "string",
"description": "Display text for the edit link.",
"default": "Edit this page"
}
}
},
"SearchConfig": {
"type": "object",
"description": "Search integration configuration. Supports 'local' (built-in) or 'algolia' (DocSearch).",
"required": ["provider"],
"properties": {
"provider": {
"type": "string",
"description": "The search provider to use.",
"enum": ["local", "algolia"]
},
"options": {
"type": "object",
"description": "Provider-specific options. For 'algolia', includes appId, apiKey, and indexName. For 'local', includes locales and other local search settings.",
"additionalProperties": true
}
}
},
"CarbonAdsConfig": {
"type": "object",
"description": "Carbon Ads configuration for displaying ads in the documentation sidebar.",
"required": ["code", "placement"],
"properties": {
"code": { "type": "string", "description": "Your Carbon Ads code." },
"placement": { "type": "string", "description": "Your Carbon Ads placement." }
}
}
}
}