Config API

Configuration resolution and helpers for VitePress

Config API

VitePress provides several utilities for working with configuration.

resolveConfig()

Resolve the VitePress site configuration.

Function Signature

export async function resolveConfig(
  root?: string,
  command?: 'serve' | 'build',
  mode?: string
): Promise<SiteConfig>

Parameters

root · string · default: "process.cwd()"

The root directory of your VitePress project containing the .vitepress folder.

command · 'serve' | 'build' · default: "'serve'"

The command being run. Affects how certain config options are resolved.

• 'serve' - Development server mode
• 'build' - Production build mode

mode · string · default: "'development'"

The mode to run in. Passed to Vite and used for environment variable loading.

Common values: 'development', 'production', or custom modes.

Return Value

SiteConfig · object

The fully resolved site configuration object.

root · string

Absolute path to the project root

srcDir · string

Absolute path to the source directory

outDir · string

Absolute path to the build output directory

cacheDir · string

Absolute path to the cache directory

tempDir · string

Absolute path to the temp directory

themeDir · string

Absolute path to the theme directory

site · SiteData

Site metadata including title, description, base, etc.

pages · string[]

List of all markdown page paths

markdown · MarkdownOptions

Markdown processing options

configPath · string | undefined

Path to the config file if found

configDeps · string[]

List of config file dependencies for watching

Examples

Basic Usage

import { resolveConfig } from 'vitepress'

const config = await resolveConfig()
console.log('Site title:', config.site.title)
console.log('Pages:', config.pages)

Build Mode

import { resolveConfig } from 'vitepress'

const config = await resolveConfig(
  process.cwd(),
  'build',
  'production'
)

console.log('Output directory:', config.outDir)

Custom Root

import { resolveConfig } from 'vitepress'
import path from 'path'

const config = await resolveConfig(
  path.resolve(__dirname, '../docs')
)

Inspect Configuration

import { resolveConfig } from 'vitepress'

const config = await resolveConfig()

console.log('Theme directory:', config.themeDir)
console.log('Markdown options:', config.markdown)
console.log('Vite config:', config.vite)
console.log('All pages:', config.pages)

---

defineConfig()

Type helper for defining VitePress configuration with TypeScript autocompletion.

Function Signature

export function defineConfig<ThemeConfig = DefaultTheme.Config>(
  config: UserConfig<NoInfer<ThemeConfig>>
): UserConfig<ThemeConfig>

Type Parameters

ThemeConfig · type · default: "DefaultTheme.Config"

The type of your theme configuration. Use this when you have a custom theme with its own config type.

Parameters

config · UserConfig<ThemeConfig>

Your VitePress configuration object.

Examples

Basic Configuration

// .vitepress/config.ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Docs',
  description: 'Documentation site',
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ]
  }
})

Custom Theme Config

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import type { ThemeConfig } from './theme/types'

export default defineConfig<ThemeConfig>({
  title: 'My Docs',
  themeConfig: {
    // TypeScript will now provide autocomplete for your custom theme config
    customOption: 'value',
    anotherOption: true
  }
})

With All Options

// .vitepress/config.ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator',
  
  base: '/docs/',
  srcDir: './src',
  outDir: './dist',
  cacheDir: './.vitepress/cache',
  
  markdown: {
    theme: 'material-theme-palenight',
    lineNumbers: true
  },
  
  themeConfig: {
    nav: [...],
    sidebar: {...}
  },
  
  vite: {
    // Vite config options
  }
})

---

defineAdditionalConfig()

Type helper for defining additional/locale-specific configuration.

Function Signature

export function defineAdditionalConfig<ThemeConfig = DefaultTheme.Config>(
  config: AdditionalConfig<NoInfer<ThemeConfig>>
): AdditionalConfig<ThemeConfig>

Examples

// docs/zh/config.ts
import { defineAdditionalConfig } from 'vitepress'

export default defineAdditionalConfig({
  lang: 'zh-CN',
  title: '我的文档',
  description: '文档站点',
  themeConfig: {
    // Chinese-specific theme config
  }
})

---

mergeConfig()

Merge two VitePress configurations.

Function Signature

export function mergeConfig(
  a: UserConfig,
  b: UserConfig,
  isRoot?: boolean
): UserConfig

Parameters

a · UserConfig

Base configuration

b · UserConfig

Configuration to merge on top of base

isRoot · boolean · default: "true"

Whether this is a root-level merge. Affects how Vite config is merged.

Examples

import { mergeConfig, defineConfig } from 'vitepress'

const baseConfig = defineConfig({
  title: 'Base Title',
  themeConfig: {
    nav: [{ text: 'Home', link: '/' }]
  }
})

const extendedConfig = defineConfig({
  description: 'Extended description',
  themeConfig: {
    nav: [{ text: 'About', link: '/about' }]
  }
})

const merged = mergeConfig(baseConfig, extendedConfig)
// Result:
// {
//   title: 'Base Title',
//   description: 'Extended description',
//   themeConfig: {
//     nav: [
//       { text: 'Home', link: '/' },
//       { text: 'About', link: '/about' }
//     ]
//   }
// }

---

resolveUserConfig()

Resolve raw user configuration from config files.

Function Signature

export async function resolveUserConfig(
  root: string,
  command: 'serve' | 'build',
  mode: string
): Promise<[UserConfig, configPath: string | undefined, configDeps: string[]]>

Return Value

Returns a tuple containing:

1. Resolved user configuration
2. Path to the config file (if found)
3. Array of config file dependencies

Examples

import { resolveUserConfig } from 'vitepress'

const [config, configPath, deps] = await resolveUserConfig(
  process.cwd(),
  'build',
  'production'
)

console.log('Config file:', configPath)
console.log('Dependencies:', deps)
console.log('User config:', config)

---

resolveSiteData()

Resolve site metadata from configuration.

Function Signature

export async function resolveSiteData(
  root: string,
  userConfig?: UserConfig,
  command?: 'serve' | 'build',
  mode?: string
): Promise<SiteData>

Examples

import { resolveSiteData } from 'vitepress'

const siteData = await resolveSiteData(process.cwd())

console.log('Title:', siteData.title)
console.log('Description:', siteData.description)
console.log('Base:', siteData.base)
console.log('Theme config:', siteData.themeConfig)

---

createServer()

Create a Vite development server for VitePress.

Function Signature

export async function createServer(
  root?: string,
  serverOptions?: ServerOptions & { base?: string },
  restartServer?: () => Promise<void>,
  config?: SiteConfig
): Promise<ViteDevServer>

Parameters

root · string · default: "process.cwd()"

Project root directory

serverOptions · ServerOptions & { base?: string }

Vite server options plus optional base path override

restartServer · () => Promise<void>

Callback function to restart the server

config · SiteConfig

Pre-resolved site config (skips config resolution if provided)

Examples

import { createServer } from 'vitepress'

const server = await createServer(process.cwd(), {
  port: 3000,
  open: true
})

await server.listen()
console.log('Dev server running at', server.resolvedUrls?.local[0])

Related

• Configuration Reference - All config options
• Default Theme Config - Theme configuration
• build() - Build API
• serve() - Preview server API