{ "$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 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 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 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." } } } } }