VitePress

Published: March 6, 2026 · Last edited: March 13, 2026

Quick reference for VitePress — a static site generator built on Vite and Vue, designed for documentation sites.

Project Structure

my-docs/
├── docs/
│   ├── .vitepress/
│   │   ├── config.js          # Site configuration
│   │   ├── theme/
│   │   │   ├── index.js       # Theme entry point
│   │   │   └── custom.css     # Custom styles
│   │   ├── cache/             # Build cache (gitignored)
│   │   └── dist/              # Build output (gitignored)
│   ├── index.md               # Homepage
│   └── guide/
│       └── getting-started.md
├── package.json
└── .gitignore

CLI Commands

# Create a new VitePress project
npx vitepress init

# Start dev server with hot reload
npx vitepress dev docs

# Build static site
npx vitepress build docs

# Preview the built site locally
npx vitepress preview docs

Or with package.json scripts:

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

Configuration

Minimal Config

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Docs',
  description: 'A VitePress site',

  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ],

    sidebar: {
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Getting Started', link: '/guide/getting-started' },
            { text: 'Configuration', link: '/guide/configuration' }
          ]
        }
      ]
    },

    search: {
      provider: 'local'
    }
  }
})

Common Options

Option	Description	Example
title	Site title (shown in nav)	'My Docs'
description	Site description (meta tag)	'A documentation site'
base	Base URL path	'/my-repo/' for GitHub Pages
appearance	Dark/light mode toggle	true (default), 'dark' (default dark)
lastUpdated	Show last updated timestamp	true
cleanUrls	Remove .html from URLs	true

Theme Customization

Override CSS variables in a custom CSS file:

:root {
  --vp-c-brand-1: #7c4dff;
  --vp-c-brand-2: #651fff;
  --vp-c-brand-3: #6200ea;
  --vp-font-family-base: 'Inter', sans-serif;
  --vp-font-family-mono: 'JetBrains Mono', monospace;
}

Register it in the theme entry point:

import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme

Markdown Extensions

Custom Containers (Callout Boxes)

::: info
This is an info box.
:::

::: tip Custom Title
This is a tip with a custom title.
:::

::: warning
This is a warning.
:::

::: danger
This is a danger alert.
:::

::: details Click to expand
This is a collapsible section.
:::

Use ::: details {open} to make a collapsible section expanded by default.

Code Features

Syntax highlighting with language identifier:

```python
print("hello")
```

Title for code blocks:

```python title="app.py"
print("hello")
```

Line highlighting — specify lines after the language:

```python {2,4-5}
def hello():
    print("highlighted")    # line 2
    x = 1
    y = 2                   # line 4
    return x + y            # line 5
```

Line numbers:

```python:line-numbers
def hello():
    print("hello")
    return True
```

Start at a custom number: ```python:line-numbers=10

Disable on a specific block: ```python:no-line-numbers

Inline Code Annotations

Add these comments at the end of any line inside a code block:

Comment	Effect
// [!code highlight]	Highlight the line
// [!code focus]	Focus this line, blur others
// [!code ++]	Green diff (added line)
// [!code --]	Red diff (removed line)
// [!code error]	Red error highlight
// [!code warning]	Yellow warning highlight

Example — showing a config change:

```js
export default {
  appearance: 'light', 
  appearance: 'dark',  
}
```

Use // [!code focus:<lines>] to focus a range of lines.

Code Groups (Tabbed)

::: code-group

```bash [npm]
npm install vitepress
```

```bash [pnpm]
pnpm add vitepress
```

```bash [yarn]
yarn add vitepress
```

:::

Code Snippet Import

Import code from existing files instead of inlining:

<<< @/snippets/example.js
<<< @/snippets/example.js{2,4-6}
<<< @/snippets/example.js#region-name
<<< ../relative/path/file.js

@/ resolves to the project source root. Use // #region name / // #endregion name in source files to define regions.

Markdown File Inclusion

<!--@include: ./shared-content.md-->
<!--@include: ./file.md{3,10}-->
<!--@include: ./file.md#region-name-->

Custom Heading Anchors

## My Section {#custom-id}

Link to it with [text](#custom-id).

Tables

Standard markdown tables work as expected:

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Frontmatter

Homepage Layout

---
layout: home

hero:
  name: Site Name
  tagline: A short description
  actions:
    - theme: brand
      text: Get Started
      link: /guide/
    - theme: alt
      text: View on GitHub
      link: https://github.com/user/repo

features:
  - title: Feature One
    details: Description of feature one.
  - title: Feature Two
    details: Description of feature two.
---

Page-Level Options

---
title: Custom Page Title
description: Custom meta description
outline: [2, 3]           # TOC depth
sidebar: false             # Hide sidebar
aside: false               # Hide right aside
lastUpdated: true          # Show last updated
prev:
  text: Previous Page
  link: /previous
next: false                # Disable next link
---

Option	Type	Default
layout	'doc' / 'home' / 'page'	'doc'
navbar	boolean	true
sidebar	boolean	true
aside	boolean / 'left'	true
outline	[number, number] / 'deep' / false	[2, 3]
lastUpdated	boolean / Date	site config
editLink	boolean	site config
pageClass	string	—
prev / next	string / false / { text, link }	auto from sidebar
footer	boolean	true

Deployment

GitHub Pages

name: Deploy VitePress

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run docs:build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Set base: '/repo-name/' in config.js if deploying to https://user.github.io/repo-name/.

Netlify / Vercel

Setting	Value
Build command	npm run docs:build
Output directory	docs/.vitepress/dist
Node version	18+

CLI Cheat Sheet

Command	What It Does
npx vitepress init	Scaffold a new project
npx vitepress dev docs	Start dev server
npx vitepress build docs	Build for production
npx vitepress preview docs	Preview the build
npx vitepress --version	Show version

Quick Reference

Task	Syntax
Info box	::: info
Tip box	::: tip
Warning box	::: warning
Danger box	::: danger
Collapsible	::: details Title
Code group	::: code-group
Line highlight	```js{1,3-5}
Line numbers	```js:line-numbers
Code title	```js title="file.js"
Diff added	// [!code ++]
Diff removed	// [!code --]
Focus line	// [!code focus]
Error line	// [!code error]
Import snippet	<<< @/path/to/file.js
Include markdown	<!--@include: ./file.md-->
Custom anchor	## Heading {#id}

Related

• MkDocs — An alternative static site generator for documentation
• Mermaid — Diagram syntax used within VitePress code blocks