Configuration
Learn how to configure VitePress to customize your documentation site's behavior, appearance, and functionality.
Overview
VitePress configuration is done through the .vitepress/config.js
(or .ts
) file in your docs directory. This file exports a configuration object that defines how your site should be built and behave.
Basic Configuration
js
// .vitepress/config.js
export default {
// Site metadata
title: 'VitePress',
description: 'Vite & Vue powered static site generator',
// Base URL for deployment
base: '/',
// Language and locale
lang: 'en-US',
// Theme configuration
themeConfig: {
// Navigation
nav: [
{ text: 'Guide', link: '/guide/' },
{ text: 'Config', link: '/config/' },
{ text: 'Examples', link: '/examples/' }
],
// Sidebar
sidebar: {
'/guide/': [
{
text: 'Getting Started',
items: [
{ text: 'Introduction', link: '/guide/' },
{ text: 'Installation', link: '/guide/installation' }
]
}
]
},
// Social links
socialLinks: [
{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }
]
}
}
Site Metadata
Basic Information
js
export default {
title: 'My Documentation',
description: 'A comprehensive guide to my project',
lang: 'en-US',
// Custom head tags
head: [
['link', { rel: 'icon', href: '/favicon.ico' }],
['meta', { name: 'theme-color', content: '#3c8772' }]
]
}
Multi-language Setup
js
export default {
locales: {
root: {
label: 'English',
lang: 'en'
},
zh: {
label: '简体中文',
lang: 'zh-CN',
link: '/zh/'
}
}
}
Theme Configuration
Navigation Bar
js
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{
text: 'Dropdown',
items: [
{ text: 'Item A', link: '/item-a' },
{ text: 'Item B', link: '/item-b' }
]
},
{
text: 'External',
link: 'https://github.com',
target: '_blank',
rel: 'noopener noreferrer'
}
]
}
Sidebar Configuration
js
themeConfig: {
sidebar: {
// Multiple sidebars for different sections
'/guide/': [
{
text: 'Introduction',
collapsed: false,
items: [
{ text: 'What is VitePress?', link: '/guide/what-is-vitepress' },
{ text: 'Getting Started', link: '/guide/getting-started' }
]
},
{
text: 'Configuration',
collapsed: false,
items: [
{ text: 'App Config', link: '/guide/app-config' },
{ text: 'Theme Config', link: '/guide/theme-config' }
]
}
],
'/examples/': [
{
text: 'Examples',
items: [
{ text: 'Basic Example', link: '/examples/basic' },
{ text: 'Advanced Example', link: '/examples/advanced' }
]
}
]
}
}
Footer Configuration
js
themeConfig: {
footer: {
message: 'Released under the MIT License.',
copyright: 'Copyright © 2024 VitePress Team'
}
}
Advanced Configuration
Custom CSS
js
export default {
// Custom CSS files
head: [
['link', { rel: 'stylesheet', href: '/custom.css' }]
],
// Vite configuration
vite: {
css: {
preprocessorOptions: {
scss: {
additionalData: `@import "@/styles/variables.scss";`
}
}
}
}
}
Build Configuration
js
export default {
// Output directory
outDir: '../dist',
// Cache directory
cacheDir: './.vitepress/cache',
// Build options
build: {
minify: 'terser',
chunkSizeWarningLimit: 1000
},
// Clean URLs
cleanUrls: true,
// Last updated timestamp
lastUpdated: true
}
Search Configuration
js
export default {
themeConfig: {
search: {
provider: 'local',
options: {
translations: {
button: {
buttonText: 'Search',
buttonAriaLabel: 'Search'
},
modal: {
noResultsText: 'No results found',
resetButtonTitle: 'Reset search',
footer: {
selectText: 'to select',
navigateText: 'to navigate'
}
}
}
}
}
}
}
Algolia Search
js
export default {
themeConfig: {
search: {
provider: 'algolia',
options: {
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_API_KEY',
indexName: 'YOUR_INDEX_NAME'
}
}
}
}
Plugin Configuration
Built-in Plugins
js
export default {
// Sitemap generation
sitemap: {
hostname: 'https://example.com'
},
// PWA support
pwa: {
mode: 'development',
base: '/',
scope: '/',
includeAssets: ['favicon.ico'],
manifest: {
name: 'VitePress PWA',
short_name: 'VitePressPWA',
theme_color: '#ffffff'
}
}
}
Custom Plugins
js
export default {
vite: {
plugins: [
// Custom Vite plugins
{
name: 'custom-plugin',
configResolved(config) {
// Plugin logic
}
}
]
}
}
Markdown Configuration
Markdown Extensions
js
export default {
markdown: {
// Line numbers in code blocks
lineNumbers: true,
// Custom containers
container: {
tipLabel: '提示',
warningLabel: '注意',
dangerLabel: '警告',
infoLabel: '信息',
detailsLabel: '详细信息'
},
// Code highlighting
theme: 'material-palenight',
// Custom markdown-it plugins
config: (md) => {
md.use(require('markdown-it-xxx'))
}
}
}
Code Block Configuration
js
export default {
markdown: {
// Syntax highlighting theme
theme: {
light: 'github-light',
dark: 'github-dark'
},
// Code groups
codeTransformers: [
// Custom transformers
]
}
}
Development Configuration
Dev Server
js
export default {
// Development server port
port: 3000,
// Open browser automatically
open: true,
// HTTPS configuration
https: {
key: 'path/to/key.pem',
cert: 'path/to/cert.pem'
}
}
Hot Module Replacement
js
export default {
vite: {
server: {
hmr: {
overlay: false
}
}
}
}
TypeScript Configuration
TypeScript Config
ts
// .vitepress/config.ts
import { defineConfig } from 'vitepress'
export default defineConfig({
title: 'VitePress',
description: 'Vite & Vue powered static site generator',
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' }
]
}
})
Type Definitions
ts
import type { DefaultTheme } from 'vitepress'
interface CustomThemeConfig extends DefaultTheme.Config {
customProperty?: string
}
export default defineConfig<CustomThemeConfig>({
themeConfig: {
customProperty: 'value'
}
})
Environment Variables
Using Environment Variables
js
export default {
define: {
__VUE_PROD_DEVTOOLS__: false,
__CUSTOM_VAR__: JSON.stringify(process.env.CUSTOM_VAR)
}
}
Runtime Environment
js
export default {
vite: {
define: {
'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV)
}
}
}
Performance Optimization
Bundle Optimization
js
export default {
vite: {
build: {
rollupOptions: {
output: {
manualChunks: {
vendor: ['vue'],
utils: ['lodash']
}
}
}
}
}
}
Asset Optimization
js
export default {
vite: {
build: {
assetsInlineLimit: 4096,
cssCodeSplit: true
}
}
}
Configuration Examples
Blog Configuration
js
export default {
title: 'My Blog',
description: 'Personal blog powered by VitePress',
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Posts', link: '/posts/' },
{ text: 'About', link: '/about' }
],
sidebar: false,
footer: {
message: 'Made with ❤️ using VitePress',
copyright: 'Copyright © 2024'
}
}
}
Documentation Site
js
export default {
title: 'Project Documentation',
description: 'Comprehensive project documentation',
themeConfig: {
logo: '/logo.svg',
nav: [
{ text: 'Guide', link: '/guide/' },
{ text: 'API', link: '/api/' },
{ text: 'Examples', link: '/examples/' }
],
sidebar: {
'/guide/': [
{
text: 'Getting Started',
items: [
{ text: 'Installation', link: '/guide/installation' },
{ text: 'Quick Start', link: '/guide/quick-start' }
]
}
]
},
editLink: {
pattern: 'https://github.com/user/repo/edit/main/docs/:path',
text: 'Edit this page on GitHub'
}
}
}
Best Practices
Configuration Organization
js
// config/nav.js
export const nav = [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' }
]
// config/sidebar.js
export const sidebar = {
'/guide/': [
// sidebar items
]
}
// .vitepress/config.js
import { nav } from './config/nav.js'
import { sidebar } from './config/sidebar.js'
export default {
themeConfig: {
nav,
sidebar
}
}
Environment-specific Configuration
js
const isDev = process.env.NODE_ENV === 'development'
export default {
base: isDev ? '/' : '/my-project/',
themeConfig: {
editLink: {
pattern: isDev
? 'vscode://file/path/to/docs/:path'
: 'https://github.com/user/repo/edit/main/docs/:path'
}
}
}
Troubleshooting
Common Issues
Build Errors
- Check file paths and imports
- Verify configuration syntax
- Ensure all dependencies are installed
Routing Issues
- Verify file structure matches routes
- Check base URL configuration
- Ensure clean URLs setting
Performance Issues
- Optimize bundle splitting
- Reduce asset sizes
- Enable compression