Site Configuration

Site configuration is where you define global settings for your VitePress site. The config file is located at .vitepress/config.js (or .ts, .mjs, .mts) and controls everything from metadata to build options.

Basic Setup

Config File Location

VitePress looks for your configuration file at:

<root>/.vitepress/config.[ext]

Supported extensions: .js, .ts, .mjs, .mts

Using defineConfig

The defineConfig helper provides TypeScript-powered intellisense:

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Documentation',
  description: 'A VitePress site',
  base: '/'
})

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Documentation',
  description: 'A VitePress site',
  base: '/'
})

TypeScript is supported out of the box - no additional configuration needed.

Dynamic Configuration

You can export an async function for dynamic configuration:

import { defineConfig } from 'vitepress'

export default async () => {
  const data = await fetchSomeData()
  
  return defineConfig({
    title: data.title,
    description: data.description
  })
}

Or use top-level await:

import { defineConfig } from 'vitepress'

const data = await fetchSomeData()

export default defineConfig({
  title: data.title,
  description: data.description
})

Site Metadata

title

string

default:"VitePress"

The title for your site. Displayed in the nav bar and used as the suffix for page titles.

export default defineConfig({
  title: 'My Awesome Docs'
})

With this configuration and a page containing # Hello, the page title becomes:

Hello | My Awesome Docs

titleTemplate

string | boolean

Customize the page title suffix or format. Use :title as a placeholder for the page title.

export default defineConfig({
  title: 'My Docs',
  titleTemplate: ':title - Custom Suffix'
})

Set to false to disable title suffixes:

export default defineConfig({
  titleTemplate: false
})

description

string

default:"A VitePress site"

Site description. Renders as a <meta> tag in the page HTML.

export default defineConfig({
  description: 'Comprehensive documentation for my project'
})

lang

string

default:"en-US"

The language attribute for the site. Renders as <html lang="...">.

export default defineConfig({
  lang: 'en-US'
})

head

HeadConfig[]

default:"[]"

Additional elements to render in the <head> tag.

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

Add a Favicon

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

Add Google Fonts

export default defineConfig({
  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' 
    }]
  ]
})

Add Analytics

export default defineConfig({
  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');
    `]
  ]
})

Directory Structure

base

string

default:"/"

The base URL for deployment. Required when deploying to a subdirectory.

export default defineConfig({
  base: '/my-project/'
})

The base must start and end with a slash. It’s automatically prepended to all URLs that start with /.

srcDir

string

default:"."

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

export default defineConfig({
  srcDir: './src'
})

outDir

string

default:"./.vitepress/dist"

The build output location, relative to project root.

export default defineConfig({
  outDir: '../public'
})

assetsDir

string

default:"assets"

Directory to nest generated assets under. Must be inside outDir.

export default defineConfig({
  assetsDir: 'static'
})

cacheDir

string

default:"./.vitepress/cache"

Directory for cache files, relative to project root.

export default defineConfig({
  cacheDir: './.vitepress/.vite'
})

srcExclude

string[]

Glob patterns for markdown files to exclude from source content.

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

Routing

cleanUrls

boolean

default:"false"

Remove trailing .html from URLs.

export default defineConfig({
  cleanUrls: true
})

Your server must be able to serve /foo.html when visiting /foo without a redirect.

rewrites

Record<string, string>

Define custom directory to URL mappings.

export default defineConfig({
  rewrites: {
    'source/:page': 'destination/:page',
    'packages/:pkg/README.md': ':pkg/index.md'
  }
})

Theming

appearance

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

default:"true"

Control dark mode behavior.

Auto (Default)
Dark by Default
Force Dark
Force Auto
Advanced

export default defineConfig({
  appearance: true // User can toggle, follows system preference
})

export default defineConfig({
  appearance: 'dark' // Dark by default, user can toggle
})

export default defineConfig({
  appearance: 'force-dark' // Always dark, no toggle
})

export default defineConfig({
  appearance: 'force-auto' // Follows system, no toggle
})

export default defineConfig({
  appearance: {
    initialValue: 'dark',
    // Additional VueUse UseDark options
  }
})

scrollOffset

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

default:"134"

Configure scroll offset for sticky headers.

export default defineConfig({
  scrollOffset: 100 // pixels
})

// Or use a selector
export default defineConfig({
  scrollOffset: '.navbar'
})

// Or multiple selectors with fallback
export default defineConfig({
  scrollOffset: ['.navbar', '.header']
})

// Or with custom padding
export default defineConfig({
  scrollOffset: {
    selector: '.navbar',
    padding: 20
  }
})

Build Options

ignoreDeadLinks

boolean | 'localhostLinks' | (string | RegExp | Function)[]

default:"false"

Control how dead links are handled during build.

Ignore All
Ignore Localhost
Pattern Matching

export default defineConfig({
  ignoreDeadLinks: true
})

export default defineConfig({
  ignoreDeadLinks: 'localhostLinks'
})

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

lastUpdated

boolean

default:"false"

Get last updated timestamp for each page using Git.

export default defineConfig({
  lastUpdated: true
})

mpa (Experimental)

boolean

default:"false"

Build in MPA mode (Multi-Page Application). Ships 0kb JavaScript but disables client-side navigation.

export default defineConfig({
  mpa: true
})

metaChunk (Experimental)

boolean

default:"false"

Extract page metadata to separate JavaScript chunks for better caching.

export default defineConfig({
  metaChunk: true
})

buildConcurrency (Experimental)

number

default:"64"

Configure build concurrency. Lower values reduce memory usage but increase build time.

export default defineConfig({
  buildConcurrency: 32
})

Integrations

vite

ViteConfig

Pass configuration to the internal Vite dev server/bundler.

export default defineConfig({
  vite: {
    plugins: [myVitePlugin()],
    server: {
      port: 3000
    },
    build: {
      chunkSizeWarningLimit: 1000
    }
  }
})

vue

VuePluginOptions

Pass options to @vitejs/plugin-vue.

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

markdown

MarkdownOptions

Configure Markdown-it parser and Shiki syntax highlighting.

export default defineConfig({
  markdown: {
    lineNumbers: true,
    theme: 'github-dark',
    config: (md) => {
      md.use(myMarkdownPlugin)
    }
  }
})

Build Hooks

buildEnd

(siteConfig: SiteConfig) => Awaitable<void>

Hook called after build finishes but before CLI process exits.

export default defineConfig({
  async buildEnd(siteConfig) {
    // Generate sitemap, search index, etc.
    console.log('Build completed!')
  }
})

postRender

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

Hook called when SSG rendering is done. Handle teleports content.

export default defineConfig({
  async postRender(context) {
    // Process teleported content
    return context
  }
})

transformHead

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

Transform head before generating each page. Return extra head entries to merge.

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

transformHtml

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

Transform HTML content before saving to disk.

export default defineConfig({
  async transformHtml(code, id, context) {
    // Modify HTML content
    return code.replace(/foo/g, 'bar')
  }
})

transformPageData

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

Transform page data for each page. Can directly mutate or return values to merge.

export default defineConfig({
  async transformPageData(pageData) {
    pageData.contributors = await getContributors(pageData.relativePath)
    
    // Or return data to merge
    return {
      readingTime: calculateReadingTime(pageData.content)
    }
  }
})

Advanced Features

Config Extension

UserConfig

Extend another configuration file.

import baseConfig from './base.config'

export default defineConfig({
  extends: baseConfig,
  title: 'Extended Config'
})

Sitemap Generation (Experimental)

SitemapStreamOptions & { hostname: string }

Configure automatic sitemap generation.

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

Content Props

Record<string, any>

Props to pass to the content component.

export default defineConfig({
  contentProps: {
    customProp: 'value'
  }
})

Router Configuration

{ prefetchLinks?: boolean }

Configure router behavior.

export default defineConfig({
  router: {
    prefetchLinks: false // Disable link prefetching
  }
})

TypeScript Configuration

Custom Theme Config Type

For custom themes, use defineConfig with a generic type:

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

export default defineConfig<ThemeConfig>({
  themeConfig: {
    // Typed according to ThemeConfig
  }
})

Environment-Specific Config

Access command and mode via function config:

import { defineConfig } from 'vitepress'

export default defineConfig(async ({ command, mode }) => {
  if (command === 'serve') {
    return {
      // Dev-specific config
    }
  } else {
    return {
      // Build-specific config
    }
  }
})

Next Steps

Theme Configuration

Configure the default theme’s appearance and behavior

Custom Theme

Create a completely custom theme

Extending Default Theme

Customize the default theme with slots and overrides

​Site Configuration

​Basic Setup

​Config File Location

​Using defineConfig

​Dynamic Configuration

​Site Metadata

​title

​titleTemplate

​description

​lang

​head

​Add a Favicon

​Add Google Fonts

​Add Analytics

​Directory Structure

​base

​srcDir

​outDir

​assetsDir

​cacheDir

​srcExclude

​Routing

​cleanUrls

​rewrites

​Theming

​appearance

​scrollOffset

​Build Options

​ignoreDeadLinks

​lastUpdated

​mpa (Experimental)

​metaChunk (Experimental)

​buildConcurrency (Experimental)

​Integrations

​vite

​vue

​markdown

​Build Hooks

​buildEnd

​postRender

​transformHead

​transformHtml

​transformPageData

​Advanced Features

​Config Extension

​Sitemap Generation (Experimental)

​Content Props

​Router Configuration

​TypeScript Configuration

​Custom Theme Config Type

​Environment-Specific Config

​Next Steps

Theme Configuration

Custom Theme

Extending Default Theme

Site Configuration

Basic Setup

Config File Location

Using defineConfig

Dynamic Configuration

Site Metadata

title

titleTemplate

description

lang

head

Add a Favicon

Add Google Fonts

Add Analytics

Directory Structure

base

srcDir

outDir

assetsDir

cacheDir

srcExclude

Routing

cleanUrls

rewrites

Theming

appearance

scrollOffset

Build Options

ignoreDeadLinks

lastUpdated

mpa (Experimental)

metaChunk (Experimental)

buildConcurrency (Experimental)

Integrations

vite

vue

markdown

Build Hooks

buildEnd

postRender

transformHead

transformHtml

transformPageData

Advanced Features

Config Extension

Sitemap Generation (Experimental)

Content Props

Router Configuration

TypeScript Configuration

Custom Theme Config Type

Environment-Specific Config

Next Steps