> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/vuejs/vitepress/llms.txt > Use this file to discover all available pages before exploring further. # Site Config Reference > Complete reference for VitePress site-level configuration options # Site Config Reference Site config defines the global settings of your VitePress site. These options apply regardless of the theme being used. ## Config File The config file is resolved from `/.vitepress/config.[ext]`, where `[ext]` can be `.js`, `.ts`, `.mjs`, or `.mts`. ```ts theme={null} import { defineConfig } from 'vitepress' export default defineConfig({ title: 'My Site', description: 'My awesome site', // ... more options }) ``` ## Site Metadata ### title Title for the site. When using the default theme, this will be displayed in the nav bar and used as the default suffix for all page titles. Can be overridden per page via frontmatter. ```ts theme={null} export default { title: 'My Awesome Site' } ``` ### titleTemplate Allows customizing each page's title suffix or the entire title. Use `:title` as a placeholder for the page's main title. Set to `false` to disable title suffixes completely. Can be overridden per page via frontmatter. ```ts theme={null} export default { titleTemplate: ':title - Custom Suffix' } ``` ### description Description for the site. Renders as a `` tag in the page HTML. Can be overridden per page via frontmatter. ```ts theme={null} export default { description: 'A VitePress site powered by Vue' } ``` ### head Additional elements to render in the `` tag. User-added tags are rendered before the closing `head` tag, after VitePress tags. Can be appended per page via frontmatter. ```ts theme={null} type HeadConfig = | [string, Record] | [string, Record, string] ``` ```ts theme={null} export default { head: [['link', { rel: 'icon', href: '/favicon.ico' }]] } ``` ```ts theme={null} export default { head: [ ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }], ['link', { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }], ['link', { href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' }] ] } ``` ```ts theme={null} export default { head: [ ['script', { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }], ['script', {}, `window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'TAG_ID');`] ] } ``` ### lang The lang attribute for the site. Renders as `` in the page HTML. ```ts theme={null} export default { lang: 'en-US' } ``` ### base The base URL the site will be deployed at. Required if deploying your site under a sub path (e.g., GitHub Pages). Must always start and end with a slash. Automatically prepended to all URLs that start with `/`. ```ts theme={null} export default { base: '/my-project/' } ``` ## Routing ### cleanUrls When `true`, VitePress removes trailing `.html` from URLs. Requires server support to serve `/foo.html` when visiting `/foo` without a redirect. ```ts theme={null} export default { cleanUrls: true } ``` ### rewrites Defines custom directory ↔ URL mappings. Allows you to customize the structure of your URLs independently of your file structure. ```ts theme={null} export default { rewrites: { 'source/:page': 'destination/:page' } } ``` ## Build ### srcDir The directory where your markdown pages are stored, relative to project root. ```ts theme={null} export default { srcDir: './src' } ``` ### srcExclude A glob pattern for matching markdown files that should be excluded as source content. ```ts theme={null} export default { srcExclude: ['**/README.md', '**/TODO.md'] } ``` ### outDir The build output location for the site, relative to project root. ```ts theme={null} export default { outDir: '../public' } ``` ### assetsDir Directory to nest generated assets under. The path should be inside `outDir` and is resolved relative to it. ```ts theme={null} export default { assetsDir: 'static' } ``` ### cacheDir The directory for cache files, relative to project root. ```ts theme={null} export default { cacheDir: './.vitepress/.vite' } ``` ### ignoreDeadLinks When `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. Can also be an array of exact URL strings, regex patterns, or custom filter functions. ```ts Simple theme={null} export default { ignoreDeadLinks: true } ``` ```ts Advanced theme={null} export default { ignoreDeadLinks: [ '/playground', /^https?:\/\/localhost/, /\/repl\//, (url) => url.toLowerCase().includes('ignore') ] } ``` ### metaChunk experimental When `true`, extract page metadata to a separate JavaScript chunk instead of inlining it in the initial HTML. Makes pages smaller and metadata cacheable. ### mpa experimental When `true`, the production app will be built in MPA Mode, shipping 0kb JavaScript by default at the cost of disabling client-side navigation. ### buildConcurrency experimental Configures the concurrency of the build. Lower numbers reduce memory usage but increase build time. ```ts theme={null} export default { buildConcurrency: 32 } ``` ## Theming ### appearance Whether to enable dark mode (by adding the `.dark` class to the `` element). * `true`: Default theme determined by user's preferred color scheme * `'dark'`: Dark by default, user can toggle * `false`: No dark mode support * `'force-dark'`: Always dark, user cannot toggle * `'force-auto'`: Always follows system preference, user cannot toggle * Object: Pass VueUse `useDark` options (with `initialValue` limited to `'dark' | undefined`) ```ts theme={null} export default { appearance: 'dark' } ``` ### lastUpdated Whether to get the last updated timestamp for each page using Git. The timestamp will be included in each page's data and displayed by the default theme. ```ts theme={null} export default { lastUpdated: true } ``` ### themeConfig Theme-specific configuration options. For the default theme, see [Theme Config Reference](/api/theme-config). ## Customization ### markdown Configure Markdown parser options. VitePress uses Markdown-it as the parser and Shiki for syntax highlighting. ```ts theme={null} export default { markdown: { theme: 'github-dark', lineNumbers: true, math: true, image: { lazyLoading: true }, codeTransformers: [ // Shiki transformers ] } } ``` **Key Options:** * `theme`: Syntax highlighting theme (string or `{ light, dark }` object) * `lineNumbers`: Show line numbers in code blocks * `languages`: Custom language support for Shiki * `languageAlias`: Map custom language names to existing languages * `defaultHighlightLang`: Fallback language when not specified * `math`: Enable math equations (requires `markdown-it-mathjax3`) * `gfmAlerts`: Enable GitHub-flavored alerts (default: `true`) * `cjkFriendlyEmphasis`: Support emphasis in CJK text (default: `true`) * `anchor`: Options for `markdown-it-anchor` * `attrs`: Options for `markdown-it-attrs` * `config`: Function to configure the markdown-it instance ### vue Pass options to the internal `@vitejs/plugin-vue` instance. ```ts theme={null} export default { vue: { template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('my-') } } } } ``` ### vite Pass raw Vite config to the internal Vite dev server / bundler. ```ts theme={null} export default { vite: { plugins: [], server: { port: 3000 }, build: { minify: 'terser' } } } ``` ### scrollOffset Configure the scroll offset when the theme has a sticky header. Can be a number, selector element, or array of selectors with fallback. ```ts theme={null} export default { scrollOffset: 90 } ``` ### contentProps Props to pass to the content component. ### router Router configuration options. * `prefetchLinks`: Whether to prefetch links on hover (default: `true`) ```ts theme={null} export default { router: { prefetchLinks: false } } ``` ### locales Locale-specific configuration. Each locale can override any site-level option. ```ts theme={null} export default { locales: { root: { label: 'English', lang: 'en' }, fr: { label: 'French', lang: 'fr', title: 'Mon Site', description: 'Mon site génial' } } } ``` ### additionalConfig experimental Multi-layer configuration overloading. Auto-resolves to `docs/.../config.{js,mjs,ts,mts}` when unspecified. Set to `{}` to opt-out. ## Build Hooks ### buildEnd Build CLI hook that runs after build (SSG) finishes but before VitePress CLI process exits. ```ts theme={null} export default { async buildEnd(siteConfig) { // Generate sitemap, search index, etc. } } ``` ### postRender Build hook called when SSG rendering is done. Allows you to handle teleports content during SSG. ```ts theme={null} interface SSGContext { content: string teleports?: Record [key: string]: any } ``` ### transformHead Build hook to transform the head before generating each page. Return extra entries that will be merged automatically. Only called during static generation, not during dev. ```ts theme={null} export default { async transformHead({ pageData }) { return [ ['meta', { property: 'og:title', content: pageData.title }] ] } } ``` ### transformHtml Build hook to transform the HTML content of each page before saving to disk. Modifying HTML content may cause hydration problems in runtime. ### transformPageData Hook to transform the `pageData` of each page. You can directly mutate `pageData` or return changed values which will be merged. Be careful as this impacts dev server performance, especially with network requests or heavy computations. ```ts theme={null} export default { async transformPageData(pageData) { pageData.contributors = await getPageContributors(pageData.relativePath) } } ``` ### sitemap experimental Sitemap generation options. Requires `hostname` to be set. ```ts theme={null} export default { sitemap: { hostname: 'https://example.com', transformItems: (items) => { return items.filter((item) => !item.url.includes('secret')) } } } ``` ### shouldPreload Function to determine which links should be preloaded. ```ts theme={null} export default { shouldPreload: (link, page) => { return !link.includes('/heavy-assets/') } } ``` ### useWebFonts Use web fonts instead of emitting font files to dist. The theme should import a file named `fonts.(s)css` for this to work. Default: `true` in webcontainers, `false` otherwise. ## Type Helpers ### defineConfig Type helper that provides TypeScript-powered intellisense for config options. ```ts theme={null} import { defineConfig } from 'vitepress' export default defineConfig({ // TypeScript autocomplete available here }) ``` ### defineConfigWithTheme For custom themes, use this to provide type checking for your custom theme config. ```ts theme={null} import { defineConfigWithTheme } from 'vitepress' import type { ThemeConfig } from 'your-theme' export default defineConfigWithTheme({ themeConfig: { // Type is ThemeConfig } }) ```