Skip to content

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

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

Next Steps

VitePress Development Guide