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 <root>/.vitepress/config.[ext], where [ext] can be .js, .ts, .mjs, or .mts.

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Site',
  description: 'My awesome site',
  // ... more options
})

Site Metadata

title

string

default:"VitePress"

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.

export default {
  title: 'My Awesome Site'
}

titleTemplate

string | boolean

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.

export default {
  titleTemplate: ':title - Custom Suffix'
}

description

string

default:"A VitePress site"

Description for the site. Renders as a <meta> tag in the page HTML.Can be overridden per page via frontmatter.

export default {
  description: 'A VitePress site powered by Vue'
}

head

HeadConfig[]

default:"[]"

Additional elements to render in the <head> tag. User-added tags are rendered before the closing head tag, after VitePress tags.Can be appended per page via frontmatter.

Show Type Definition

type HeadConfig =
  | [string, Record<string, string>]
  | [string, Record<string, string>, string]

Favicon
Google Fonts
Analytics

export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
}

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' }]
  ]
}

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

string

default:"en-US"

The lang attribute for the site. Renders as <html lang="en-US"> in the page HTML.

export default {
  lang: 'en-US'
}

base

string

default:"/"

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 /.

export default {
  base: '/my-project/'
}

Routing

cleanUrls

boolean

default:"false"

When true, VitePress removes trailing .html from URLs.

Requires server support to serve /foo.html when visiting /foo without a redirect.

export default {
  cleanUrls: true
}

rewrites

Record<string, string> | ((id: string) => string)

Defines custom directory ↔ URL mappings. Allows you to customize the structure of your URLs independently of your file structure.

export default {
  rewrites: {
    'source/:page': 'destination/:page'
  }
}

Build

srcDir

string

default:"."

The directory where your markdown pages are stored, relative to project root.

export default {
  srcDir: './src'
}

srcExclude

string[]

A glob pattern for matching markdown files that should be excluded as source content.

export default {
  srcExclude: ['**/README.md', '**/TODO.md']
}

outDir

string

default:"./.vitepress/dist"

The build output location for the site, relative to project root.

export default {
  outDir: '../public'
}

assetsDir

string

default:"assets"

Directory to nest generated assets under. The path should be inside outDir and is resolved relative to it.

export default {
  assetsDir: 'static'
}

cacheDir

string

default:"./.vitepress/cache"

The directory for cache files, relative to project root.

export default {
  cacheDir: './.vitepress/.vite'
}

ignoreDeadLinks

boolean | 'localhostLinks' | (string | RegExp | ((link: string, source: string) => boolean))[]

default:"false"

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.

export default {
  ignoreDeadLinks: true
}

export default {
  ignoreDeadLinks: [
    '/playground',
    /^https?:\/\/localhost/,
    /\/repl\//,
    (url) => url.toLowerCase().includes('ignore')
  ]
}

metaChunk

boolean

default:"false"

experimentalWhen true, extract page metadata to a separate JavaScript chunk instead of inlining it in the initial HTML. Makes pages smaller and metadata cacheable.

mpa

boolean

default:"false"

experimentalWhen true, the production app will be built in MPA Mode, shipping 0kb JavaScript by default at the cost of disabling client-side navigation.

buildConcurrency

number

default:"64"

experimentalConfigures the concurrency of the build. Lower numbers reduce memory usage but increase build time.

export default {
  buildConcurrency: 32
}

Theming

appearance

boolean | 'dark' | 'force-dark' | 'force-auto' | UseDarkOptions

default:"true"

Whether to enable dark mode (by adding the .dark class to the <html> 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)

export default {
  appearance: 'dark'
}

lastUpdated

boolean

default:"false"

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.

export default {
  lastUpdated: true
}

themeConfig

ThemeConfig

Theme-specific configuration options. For the default theme, see Theme Config Reference.

Customization

markdown

MarkdownOptions

Configure Markdown parser options. VitePress uses Markdown-it as the parser and Shiki for syntax highlighting.

Show Common Options

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

VuePluginOptions

Pass options to the internal @vitejs/plugin-vue instance.

export default {
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag) => tag.startsWith('my-')
      }
    }
  }
}

vite

ViteConfig

Pass raw Vite config to the internal Vite dev server / bundler.

export default {
  vite: {
    plugins: [],
    server: {
      port: 3000
    },
    build: {
      minify: 'terser'
    }
  }
}

scrollOffset

number | string | string[] | { selector: string | string[]; padding: number }

default:"134"

Configure the scroll offset when the theme has a sticky header. Can be a number, selector element, or array of selectors with fallback.

export default {
  scrollOffset: 90
}

contentProps

Record<string, any>

Props to pass to the content component.

router

{ prefetchLinks?: boolean }

Router configuration options.

prefetchLinks: Whether to prefetch links on hover (default: true)

export default {
  router: {
    prefetchLinks: false
  }
}

locales

LocaleConfig<ThemeConfig>

Locale-specific configuration. Each locale can override any site-level option.

export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    fr: {
      label: 'French',
      lang: 'fr',
      title: 'Mon Site',
      description: 'Mon site génial'
    }
  }
}

additionalConfig

AdditionalConfigDict | AdditionalConfigLoader

experimentalMulti-layer configuration overloading. Auto-resolves to docs/.../config.{js,mjs,ts,mts} when unspecified. Set to {} to opt-out.

Build Hooks

buildEnd

(siteConfig: SiteConfig) => Awaitable<void>

Build CLI hook that runs after build (SSG) finishes but before VitePress CLI process exits.

export default {
  async buildEnd(siteConfig) {
    // Generate sitemap, search index, etc.
  }
}

postRender

(context: SSGContext) => Awaitable<SSGContext | void>

Build hook called when SSG rendering is done. Allows you to handle teleports content during SSG.

Show SSGContext Interface

interface SSGContext {
  content: string
  teleports?: Record<string, string>
  [key: string]: any
}

transformHead

(context: TransformContext) => Awaitable<HeadConfig[]>

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.

export default {
  async transformHead({ pageData }) {
    return [
      ['meta', { property: 'og:title', content: pageData.title }]
    ]
  }
}

transformHtml

(code: string, id: string, context: TransformContext) => Awaitable<string | void>

Build hook to transform the HTML content of each page before saving to disk.

Modifying HTML content may cause hydration problems in runtime.

transformPageData

(pageData: PageData, context: TransformPageContext) => Awaitable<Partial<PageData> | void>

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.

export default {
  async transformPageData(pageData) {
    pageData.contributors = await getPageContributors(pageData.relativePath)
  }
}

sitemap

SitemapStreamOptions & { hostname: string; transformItems?: (items: SitemapItem[]) => Awaitable<SitemapItem[]> }

experimentalSitemap generation options. Requires hostname to be set.

export default {
  sitemap: {
    hostname: 'https://example.com',
    transformItems: (items) => {
      return items.filter((item) => !item.url.includes('secret'))
    }
  }
}

shouldPreload

(link: string, page: string) => boolean

Function to determine which links should be preloaded.

export default {
  shouldPreload: (link, page) => {
    return !link.includes('/heavy-assets/')
  }
}

useWebFonts

boolean

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.

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.

import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'your-theme'

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    // Type is ThemeConfig
  }
})

​Site Config Reference

​Config File

​Site Metadata

​title

​titleTemplate

​description

​head

​lang

​base

​Routing

​cleanUrls

​rewrites

​Build

​srcDir

​srcExclude

​outDir

​assetsDir

​cacheDir

​ignoreDeadLinks

​metaChunk

​mpa

​buildConcurrency

​Theming

​appearance

​lastUpdated

​themeConfig

​Customization

​markdown

​vue

​vite

​scrollOffset

​contentProps

​router

​locales

​additionalConfig

​Build Hooks

​buildEnd

​postRender

​transformHead

​transformHtml

​transformPageData

​sitemap

​shouldPreload

​useWebFonts

​Type Helpers

​defineConfig

​defineConfigWithTheme

Site Config Reference

Config File

Site Metadata

title

titleTemplate

description

head

lang

base

Routing

cleanUrls

rewrites

Build

srcDir

srcExclude

outDir

assetsDir

cacheDir

ignoreDeadLinks

metaChunk

mpa

buildConcurrency

Theming

appearance

lastUpdated

themeConfig

Customization

markdown

vue

vite

scrollOffset

contentProps

router

locales

additionalConfig

Build Hooks

buildEnd

postRender

transformHead

transformHtml

transformPageData

sitemap

shouldPreload

useWebFonts

Type Helpers

defineConfig

defineConfigWithTheme