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
The fully resolved site configuration object.Absolute path to the project root
Absolute path to the source directory
Absolute path to the build output directory
Absolute path to the cache directory
Absolute path to the temp directory
Absolute path to the theme directory
Site metadata including title, description, base, etc.
List of all markdown page paths
Markdown processing options
Path to the config file if found
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
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
Configuration to merge on top of base
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:
- Resolved user configuration
- Path to the config file (if found)
- 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
Callback function to restart the server
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])