Site Configuration

Learn how to configure your VitePress site with comprehensive configuration options.

Basic Configuration

Configuration File

Create .vitepress/config.js (or .ts for TypeScript):

javascript

// .vitepress/config.js
export default {
  // Site metadata
  title: 'My Awesome Site',
  description: 'A VitePress site with great content',
  
  // Base URL for deployment
  base: '/',
  
  // Language
  lang: 'en-US',
  
  // Clean URLs (remove .html extension)
  cleanUrls: true
}

TypeScript Configuration

Use TypeScript for better development experience:

typescript

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

export default defineConfig({
  title: 'My Awesome Site',
  description: 'A VitePress site with great content',
  
  // TypeScript provides autocomplete and type checking
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ]
  }
})

Site Metadata

Basic Metadata

Configure essential site information:

javascript

export default {
  title: 'VitePress Documentation',
  titleTemplate: ':title - VitePress',
  description: 'Vite & Vue powered static site generator',
  
  // HTML head configuration
  head: [
    ['meta', { charset: 'utf-8' }],
    ['meta', { name: 'viewport', content: 'width=device-width, initial-scale=1' }],
    ['link', { rel: 'icon', href: '/favicon.ico' }]
  ],
  
  // Language and locale
  lang: 'en-US',
  
  // Appearance
  appearance: true, // Enable dark mode toggle
  
  // Last updated timestamp
  lastUpdated: true
}

Advanced Head Configuration

Add complex head elements:

javascript

export default {
  head: [
    // Favicon
    ['link', { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }],
    ['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicon-32x32.png' }],
    ['link', { rel: 'icon', type: 'image/png', sizes: '16x16', href: '/favicon-16x16.png' }],
    
    // Apple touch icon
    ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/apple-touch-icon.png' }],
    
    // Manifest
    ['link', { rel: 'manifest', href: '/site.webmanifest' }],
    
    // Theme color
    ['meta', { name: 'theme-color', content: '#3eaf7c' }],
    
    // Open Graph
    ['meta', { property: 'og:type', content: 'website' }],
    ['meta', { property: 'og:locale', content: 'en' }],
    ['meta', { property: 'og:site_name', content: 'VitePress' }],
    ['meta', { property: 'og:image', content: 'https://vitepress.dev/vitepress-logo-large.webp' }],
    
    // Twitter
    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
    ['meta', { name: 'twitter:site', content: '@vuepress' }],
    
    // Preconnect to external domains
    ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }],
    ['link', { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }],
    
    // Google Fonts
    ['link', { href: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap', rel: 'stylesheet' }],
    
    // Analytics
    ['script', { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID' }],
    ['script', {}, `
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'GA_MEASUREMENT_ID');
    `]
  ]
}

Build Configuration

Output Directory

Configure build output:

javascript

export default {
  // Output directory (relative to project root)
  outDir: '../dist',
  
  // Assets directory (relative to outDir)
  assetsDir: 'assets',
  
  // Cache directory
  cacheDir: '.vitepress/cache',
  
  // Temporary directory
  tempDir: '.vitepress/temp'
}

Clean URLs

Configure URL structure:

javascript

export default {
  // Remove .html extension from URLs
  cleanUrls: true,
  
  // Custom URL rewrites
  rewrites: {
    'packages/:pkg/(.*)': ':pkg/index.md'
  }
}

Base URL

Configure for deployment to subdirectories:

javascript

export default {
  // For deployment to https://example.com/docs/
  base: '/docs/',
  
  // For deployment to root domain
  base: '/'
}

Multi-language Configuration

Locales Setup

Configure multiple languages:

javascript

export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en',
      title: 'VitePress',
      description: 'Vite & Vue powered static site generator'
    },
    zh: {
      label: '简体中文',
      lang: 'zh-CN',
      title: 'VitePress',
      description: 'Vite & Vue 驱动的静态网站生成器',
      link: '/zh/'
    },
    es: {
      label: 'Español',
      lang: 'es-ES',
      title: 'VitePress',
      description: 'Generador de sitios estáticos con Vite y Vue',
      link: '/es/'
    }
  }
}

Locale-specific Configuration

Different configurations per locale:

javascript

export default {
  locales: {
    root: {
      themeConfig: {
        nav: [
          { text: 'Guide', link: '/guide/' },
          { text: 'API', link: '/api/' }
        ]
      }
    },
    zh: {
      themeConfig: {
        nav: [
          { text: '指南', link: '/zh/guide/' },
          { text: 'API', link: '/zh/api/' }
        ]
      }
    }
  }
}

Advanced Configuration

Custom Markdown Configuration

Extend markdown processing:

javascript

export default {
  markdown: {
    // Line numbers in code blocks
    lineNumbers: true,
    
    // Custom anchor configuration
    anchor: {
      permalink: true,
      permalinkBefore: true,
      permalinkSymbol: '#'
    },
    
    // Table of contents
    toc: {
      includeLevel: [1, 2, 3]
    },
    
    // Custom markdown-it configuration
    config: (md) => {
      // Add custom plugins
      md.use(require('markdown-it-footnote'))
      md.use(require('markdown-it-deflist'))
      
      // Custom renderer rules
      md.renderer.rules.heading_close = (tokens, idx, options, env, renderer) => {
        let htmlResult = renderer.renderToken(tokens, idx, options)
        if (tokens[idx].tag === 'h1') htmlResult += `\n<hr class="custom-hr">`
        return htmlResult
      }
    }
  }
}

Vite Configuration

Integrate with Vite:

javascript

export default {
  vite: {
    // Define global constants
    define: {
      __VUE_OPTIONS_API__: false
    },
    
    // Server configuration
    server: {
      host: true,
      port: 3000,
      open: true
    },
    
    // Build configuration
    build: {
      minify: 'terser',
      chunkSizeWarningLimit: 1000
    },
    
    // CSS configuration
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import "/styles/variables.scss";`
        }
      }
    },
    
    // Plugin configuration
    plugins: [
      // Add Vite plugins
    ]
  }
}

Build Hooks

Add custom build logic:

javascript

export default {
  // Transform page data
  transformPageData(pageData) {
    // Add reading time
    const content = pageData.content || ''
    const wordsPerMinute = 200
    const wordCount = content.split(/\s+/).length
    const readingTime = Math.ceil(wordCount / wordsPerMinute)
    
    pageData.frontmatter.readingTime = readingTime
    
    return pageData
  },
  
  // Transform HTML
  transformHtml: (code, id, context) => {
    // Add custom HTML transformations
    return code.replace(
      /<title>(.*?)<\/title>/,
      `<title>$1 | My Site</title>`
    )
  },
  
  // Build start hook
  buildStart() {
    console.log('Build started!')
  },
  
  // Build end hook
  buildEnd(siteConfig) {
    console.log('Build completed!')
    
    // Generate additional files
    generateSitemap(siteConfig)
    generateRobotsTxt(siteConfig)
  }
}

Environment Configuration

Environment Variables

Use environment variables:

javascript

export default {
  title: process.env.SITE_TITLE || 'Default Title',
  description: process.env.SITE_DESCRIPTION || 'Default description',
  
  head: [
    // Conditional analytics
    ...(process.env.NODE_ENV === 'production' ? [
      ['script', { async: '', src: `https://www.googletagmanager.com/gtag/js?id=${process.env.GA_ID}` }]
    ] : [])
  ],
  
  vite: {
    define: {
      __API_URL__: JSON.stringify(process.env.API_URL || 'http://localhost:3000'),
      __VERSION__: JSON.stringify(process.env.npm_package_version)
    }
  }
}

Development vs Production

Different configurations for different environments:

javascript

const isDev = process.env.NODE_ENV === 'development'
const isProd = process.env.NODE_ENV === 'production'

export default {
  title: 'My Site',
  description: 'My awesome site',
  
  // Development-specific configuration
  ...(isDev && {
    vite: {
      server: {
        port: 3000,
        open: true
      }
    }
  }),
  
  // Production-specific configuration
  ...(isProd && {
    cleanUrls: true,
    sitemap: {
      hostname: 'https://mysite.com'
    }
  })
}

Configuration Validation

TypeScript Validation

Use TypeScript for configuration validation:

typescript

import { defineConfig, type UserConfig } from 'vitepress'

const config: UserConfig = {
  title: 'My Site',
  description: 'My description',
  
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ]
  }
}

export default defineConfig(config)

Runtime Validation

Add runtime configuration validation:

javascript

function validateConfig(config) {
  const errors = []
  
  if (!config.title) {
    errors.push('Title is required')
  }
  
  if (!config.description) {
    errors.push('Description is required')
  }
  
  if (config.base && !config.base.startsWith('/')) {
    errors.push('Base must start with /')
  }
  
  if (errors.length > 0) {
    throw new Error(`Configuration errors:\n${errors.join('\n')}`)
  }
  
  return config
}

export default validateConfig({
  title: 'My Site',
  description: 'My description'
})

Best Practices

Organization

Use TypeScript for better development experience
Separate configuration by environment
Use environment variables for sensitive data
Document custom configuration options

Performance

Optimize head elements
Use appropriate build settings
Configure proper caching headers
Minimize bundle size

SEO

Include proper meta tags
Configure Open Graph data
Set up structured data
Generate sitemaps

Maintainability

Use consistent naming conventions
Add comments for complex configurations
Validate configuration at build time
Keep configuration DRY (Don't Repeat Yourself)

Site Configuration ​

Basic Configuration ​

Configuration File ​

TypeScript Configuration ​

Site Metadata ​

Basic Metadata ​

Advanced Head Configuration ​

Build Configuration ​

Output Directory ​

Clean URLs ​

Base URL ​

Multi-language Configuration ​

Locales Setup ​

Locale-specific Configuration ​

Advanced Configuration ​

Custom Markdown Configuration ​

Vite Configuration ​

Build Hooks ​

Environment Configuration ​

Environment Variables ​

Development vs Production ​

Configuration Validation ​

TypeScript Validation ​

Runtime Validation ​

Best Practices ​

Organization ​

Performance ​

SEO ​

Maintainability ​

Site Configuration

Basic Configuration

Configuration File

TypeScript Configuration

Site Metadata

Basic Metadata

Advanced Head Configuration

Build Configuration

Output Directory

Clean URLs

Base URL

Multi-language Configuration

Locales Setup

Locale-specific Configuration

Advanced Configuration

Custom Markdown Configuration

Vite Configuration

Build Hooks

Environment Configuration

Environment Variables

Development vs Production

Configuration Validation

TypeScript Validation

Runtime Validation

Best Practices

Organization

Performance

SEO

Maintainability