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." }
}
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/vitepress-config"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"Discovery needs no key. Ratings and market analysis are Pro.