Reference

Complete API reference and configuration options for VitePress.

Configuration Reference

Site Config

Basic Options

interface SiteConfig {
  /**
   * Title of the site. This will be displayed in the nav bar.
   * Also used as the suffix for all page titles unless `titleTemplate` is defined.
   */
  title?: string

  /**
   * Description of the site. This will render as a <meta> tag in the page HTML.
   */
  description?: string

  /**
   * Base URL the site will be deployed at.
   * @default '/'
   */
  base?: string

  /**
   * Language of the site. This will render as a lang attribute in the page HTML.
   * @default 'en-US'
   */
  lang?: string

  /**
   * Directory to serve as the source directory.
   * @default 'docs'
   */
  srcDir?: string

  /**
   * Directory to save the built files, relative to project root.
   * @default '.vitepress/dist'
   */
  outDir?: string

  /**
   * Directory to save cache files.
   * @default '.vitepress/cache'
   */
  cacheDir?: string

  /**
   * Whether to include the last updated timestamp for each page.
   * @default false
   */
  lastUpdated?: boolean

  /**
   * Whether to enable clean URLs.
   * @default false
   */
  cleanUrls?: boolean
}

Advanced Options

interface AdvancedSiteConfig {
  /**
   * Custom title template for the page.
   * @example ':title - Custom Suffix'
   */
  titleTemplate?: string | boolean

  /**
   * Appearance mode.
   * @default 'auto'
   */
  appearance?: 'dark' | 'light' | 'auto'

  /**
   * Custom head tags to be rendered.
   */
  head?: HeadConfig[]

  /**
   * Locale configuration for multi-language sites.
   */
  locales?: Record<string, LocaleConfig>

  /**
   * Markdown configuration.
   */
  markdown?: MarkdownConfig

  /**
   * Vite configuration.
   */
  vite?: ViteConfig

  /**
   * Build hooks.
   */
  buildEnd?: (siteConfig: SiteConfig) => void | Promise<void>
  postRender?: (context: SSGContext) => void | Promise<void>
  transformHead?: (context: TransformContext) => void | Promise<void>
  transformHtml?: (code: string, id: string, context: TransformContext) => void | Promise<void>
  transformPageData?: (pageData: PageData, context: TransformContext) => void | Promise<void>
}

Theme Config

Default Theme Configuration

interface DefaultThemeConfig {
  /**
   * Logo file path.
   */
  logo?: string

  /**
   * Custom site title. If not set, `config.title` will be used.
   */
  siteTitle?: string | false

  /**
   * Navigation menu items.
   */
  nav?: NavItem[]

  /**
   * Sidebar configuration.
   */
  sidebar?: Sidebar

  /**
   * Social links to be displayed at the end of the nav bar.
   */
  socialLinks?: SocialLink[]

  /**
   * Footer configuration.
   */
  footer?: Footer

  /**
   * Edit link configuration.
   */
  editLink?: EditLink

  /**
   * Last updated text configuration.
   */
  lastUpdated?: LastUpdatedOptions

  /**
   * Search configuration.
   */
  search?: SearchConfig

  /**
   * Carbon ads configuration.
   */
  carbonAds?: CarbonAdsConfig

  /**
   * Doc footer configuration.
   */
  docFooter?: DocFooter

  /**
   * Outline configuration.
   */
  outline?: Outline

  /**
   * Return to top label.
   */
  returnToTopLabel?: string

  /**
   * External link icon configuration.
   */
  externalLinkIcon?: boolean
}

interface NavItem {
  /**
   * The text label of the item.
   */
  text: string

  /**
   * The link of the item.
   */
  link?: string

  /**
   * The children of the item.
   */
  items?: NavItem[]

  /**
   * `activeMatch` is expected to be a regex string. We can't use actual
   * RegExp object here because it's not serializable
   */
  activeMatch?: string

  /**
   * `rel` attribute for the link.
   */
  rel?: string

  /**
   * `target` attribute for the link.
   */
  target?: string
}

type Sidebar = SidebarItem[] | SidebarMulti

interface SidebarItem {
  /**
   * The text label of the item.
   */
  text?: string

  /**
   * The link of the item.
   */
  link?: string

  /**
   * The children of the item.
   */
  items?: SidebarItem[]

  /**
   * If not specified, group is not collapsible.
   * If `true`, group is collapsible and collapsed by default
   * If `false`, group is collapsible but expanded by default
   */
  collapsed?: boolean
}

interface SidebarMulti {
  [path: string]: SidebarItem[]
}

Markdown Configuration

interface MarkdownConfig {
  /**
   * Enable line numbers in code blocks.
   * @default false
   */
  lineNumbers?: boolean

  /**
   * Markdown-it configuration function.
   */
  config?: (md: MarkdownIt) => void

  /**
   * Syntax highlighting theme.
   * @default 'material-theme-palenight'
   */
  theme?: 
    | string
    | { light: string; dark: string }

  /**
   * Custom containers configuration.
   */
  container?: {
    tipLabel?: string
    warningLabel?: string
    dangerLabel?: string
    infoLabel?: string
    detailsLabel?: string
  }

  /**
   * Math support configuration.
   */
  math?: boolean

  /**
   * Code transformers.
   */
  codeTransformers?: CodeTransformer[]
}

API Reference

useData()

Access page and site data in Vue components.

interface VitePressData {
  /**
   * Site-level metadata
   */
  site: Ref<SiteData>

  /**
   * themeConfig from .vitepress/config.js
   */
  theme: Ref<DefaultTheme.Config>

  /**
   * Page-level metadata
   */
  page: Ref<PageData>

  /**
   * Page frontmatter data
   */
  frontmatter: Ref<PageData['frontmatter']>

  /**
   * Dynamic route params
   */
  params: Ref<PageData['params']>

  /**
   * Current page title
   */
  title: Ref<string>

  /**
   * Current page description
   */
  description: Ref<string>

  /**
   * Current page language
   */
  lang: Ref<string>

  /**
   * Whether the page is 404
   */
  isDark: Ref<boolean>

  /**
   * Current page directory
   */
  dir: Ref<string>

  /**
   * Current locale path
   */
  localeIndex: Ref<string>
}

Usage:

vue

<script setup>
import { useData } from 'vitepress'

const { site, theme, page, frontmatter } = useData()
</script>

<template>
  <h1>{{ site.title }}</h1>
  <p>{{ page.title }}</p>
  <p>{{ frontmatter.description }}</p>
</template>

useRouter()

Access router instance for navigation.

interface Router {
  /**
   * Current route location
   */
  route: Route

  /**
   * Navigate to a different location
   */
  go: (to?: string) => Promise<void>

  /**
   * Register a callback to be called before each route change
   */
  onBeforeRouteChange?: (to: string) => void

  /**
   * Register a callback to be called after each route change
   */
  onAfterRouteChanged?: (to: string) => void
}

Usage:

vue

<script setup>
import { useRouter } from 'vitepress'

const router = useRouter()

const navigateToGuide = () => {
  router.go('/guide/')
}
</script>

Content Component

Render markdown content in Vue components.

vue

<template>
  <div class="custom-layout">
    <aside class="sidebar">
      <!-- Custom sidebar -->
    </aside>
    <main class="content">
      <Content />
    </main>
  </div>
</template>

Frontmatter Reference

Page Frontmatter

yaml

---
# Page title (overrides h1)
title: Custom Page Title

# Page description for SEO
description: This is a custom page description

# Layout to use for this page
layout: home | page | doc

# Whether to show the page in sidebar
sidebar: true | false

# Whether to show edit link
editLink: true | false

# Whether to show last updated
lastUpdated: true | false

# Whether to show prev/next links
prev: true | false | string | { text: string, link: string }
next: true | false | string | { text: string, link: string }

# Page-specific head tags
head:
  - - meta
    - name: description
      content: Custom description
  - - meta
    - name: keywords
      content: keyword1, keyword2

# Outline configuration for this page
outline: false | [number, number] | 'deep'

# Custom page class
pageClass: custom-page-class
---

Home Layout Frontmatter

yaml

---
layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator
  tagline: Simple, powerful, and performant. Meet the modern SSG framework you've always wanted.
  image:
    src: /logo-with-shadow.png
    alt: VitePress
  actions:
    - theme: brand
      text: Get Started
      link: /guide/what-is-vitepress
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress

features:
  - icon: 📝
    title: Focus on Your Content
    details: Effortlessly create beautiful documentation sites with just markdown.
  - icon: 🎨
    title: Enjoy the Vue DX
    details: Use Vue syntax and components directly in markdown, or build custom themes with Vue.
  - icon: 🚀
    title: Ship Fast Sites
    details: Fast dev server startup. Lightning fast hot updates. Optimized build output.
---

CLI Reference

Commands

bash

# Start development server
vitepress dev [root]

# Build for production
vitepress build [root]

# Preview production build
vitepress preview [root]

# Initialize VitePress in current directory
vitepress init

Options

bash

# Development server options
vitepress dev --port 3000 --host 0.0.0.0 --open

# Build options
vitepress build --outDir dist --base /my-site/

# Preview options
vitepress preview --port 4173 --host localhost

Environment Variables

Build-time Variables

bash

# Node environment
NODE_ENV=production

# Base URL for deployment
VITE_BASE_URL=/my-site/

# API endpoint
VITE_API_URL=https://api.example.com

# Feature flags
VITE_FEATURE_ANALYTICS=true

Runtime Access

// Access environment variables in components
const apiUrl = import.meta.env.VITE_API_URL
const isDev = import.meta.env.DEV
const isProd = import.meta.env.PROD

File Conventions

Directory Structure

.
├── docs/
│   ├── .vitepress/
│   │   ├── config.js          # Configuration file
│   │   ├── theme/             # Custom theme
│   │   │   ├── index.js       # Theme entry
│   │   │   ├── Layout.vue     # Layout component
│   │   │   └── style.css      # Custom styles
│   │   └── dist/              # Build output
│   ├── guide/
│   │   ├── index.md
│   │   └── getting-started.md
│   ├── api/
│   │   └── reference.md
│   ├── public/                # Static assets
│   │   ├── favicon.ico
│   │   └── logo.png
│   └── index.md               # Homepage
└── package.json

File Naming

Markdown files: Use kebab-case (getting-started.md)
Vue components: Use PascalCase (MyComponent.vue)
Assets: Use descriptive names (hero-image.png)
Configuration: Use standard names (config.js, package.json)

TypeScript Support

Configuration

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

export default defineConfig({
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator'
})

Theme Development

// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app, router, siteData }) {
    // Type-safe theme customization
  }
} satisfies Theme

Component Types

vue

<script setup lang="ts">
import { useData } from 'vitepress'
import type { DefaultTheme } from 'vitepress/theme'

interface Props {
  title: string
  items: DefaultTheme.NavItem[]
}

const props = defineProps<Props>()
const { site, theme } = useData()
</script>

Migration Guide

From VuePress 1.x

Update dependencies

bash

npm uninstall vuepress
npm install -D vitepress

Update configuration

// Before (VuePress)
module.exports = {
  title: 'My Site',
  themeConfig: {
    nav: [...]
  }
}

// After (VitePress)
export default {
  title: 'My Site',
  themeConfig: {
    nav: [...]
  }
}

Update theme structure

// Before
.vuepress/
├── config.js
└── theme/
    └── Layout.vue

// After
.vitepress/
├── config.js
└── theme/
    ├── index.js
    └── Layout.vue

From VuePress 2.x

Configuration changes

// VuePress 2.x
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  // config
})

// VitePress
import { defineConfig } from 'vitepress'

export default defineConfig({
  // config
})

Plugin system differences

// VuePress 2.x uses plugins array
export default {
  plugins: [
    ['@vuepress/plugin-search'],
    ['@vuepress/plugin-pwa']
  ]
}

// VitePress uses Vite plugins
export default {
  vite: {
    plugins: [
      // Vite plugins
    ]
  }
}

Performance Tips

Bundle Optimization

// .vitepress/config.js
export default {
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['vue'],
            utils: ['lodash', 'date-fns']
          }
        }
      }
    }
  }
}

Asset Optimization

export default {
  vite: {
    build: {
      assetsInlineLimit: 4096,
      cssCodeSplit: true,
      sourcemap: false
    }
  }
}

Code Splitting

vue

<script setup>
// Use dynamic imports for heavy components
const HeavyComponent = defineAsyncComponent(() => 
  import('./HeavyComponent.vue')
)
</script>

Troubleshooting

Common Issues

Build Errors

Check Node.js version (18+)
Verify configuration syntax
Clear cache: rm -rf .vitepress/cache

Routing Issues

Verify file structure matches routes
Check base URL configuration
Ensure proper file extensions

Performance Issues

Analyze bundle size: npm run build -- --analyze
Optimize images and assets
Review third-party dependencies

Debug Mode

bash

# Enable debug logging
DEBUG=vitepress:* npm run dev

# Verbose build output
npm run build -- --debug

Resources

Official Documentation

Community

Tools

This reference guide covers the most commonly used APIs and configurations. For the latest updates, always refer to the official VitePress documentation.

Reference ​

Configuration Reference ​

Site Config ​

Basic Options ​

Advanced Options ​

Theme Config ​

Default Theme Configuration ​

Navigation Configuration ​

Sidebar Configuration ​

Markdown Configuration ​

API Reference ​

useData() ​

useRouter() ​

Content Component ​

Frontmatter Reference ​

Page Frontmatter ​

Home Layout Frontmatter ​

CLI Reference ​

Commands ​

Options ​

Environment Variables ​

Build-time Variables ​

Runtime Access ​

File Conventions ​

Directory Structure ​

File Naming ​

TypeScript Support ​

Configuration ​

Theme Development ​

Component Types ​

Migration Guide ​

From VuePress 1.x ​

From VuePress 2.x ​

Performance Tips ​

Bundle Optimization ​

Asset Optimization ​

Code Splitting ​

Troubleshooting ​

Common Issues ​

Debug Mode ​

Resources ​

Official Documentation ​

Community ​

Tools ​

Reference

Configuration Reference

Site Config

Basic Options

Advanced Options

Theme Config

Default Theme Configuration

Navigation Configuration

Sidebar Configuration

Markdown Configuration

API Reference

useData()

useRouter()

Content Component

Frontmatter Reference

Page Frontmatter

Home Layout Frontmatter

CLI Reference

Commands

Options

Environment Variables

Build-time Variables

Runtime Access

File Conventions

Directory Structure

File Naming

TypeScript Support

Configuration

Theme Development

Component Types

Migration Guide

From VuePress 1.x

From VuePress 2.x

Performance Tips

Bundle Optimization

Asset Optimization

Code Splitting

Troubleshooting

Common Issues

Debug Mode

Resources

Official Documentation

Community

Tools