VitePress Guide

Comprehensive guide to VitePress - the modern static site generator powered by Vite and Vue.

What is VitePress?

VitePress is a static site generator (SSG) designed to create fast, content-focused websites. Built on top of Vite and Vue.js, it combines the best of both worlds: the speed of Vite's development experience and the power of Vue's component system.

Key Features

⚡ Lightning Fast: Powered by Vite for instant hot module replacement
📝 Markdown-Centered: Write content in Markdown with Vue component support
🎨 Customizable: Flexible theming system with Vue.js
🔍 Built-in Search: Local search functionality out of the box
📱 Mobile Optimized: Responsive design that works on all devices
🚀 Production Ready: Optimized builds with code splitting

Getting Started

Installation

bash

# Create a new project
mkdir my-vitepress-site
cd my-vitepress-site

# Initialize package.json
npm init -y

# Install VitePress
npm install -D vitepress

# Create your first document
mkdir docs
echo '# Hello VitePress' > docs/index.md

Basic Configuration

Create .vitepress/config.js:

export default {
  title: 'My VitePress Site',
  description: 'A VitePress site powered by Vite and Vue',
  
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ],
    
    sidebar: [
      {
        text: 'Getting Started',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Installation', link: '/installation' }
        ]
      }
    ]
  }
}

Development Scripts

Add to your package.json:

json

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

Start Development Server

bash

npm run docs:dev

Core Concepts

File-Based Routing

VitePress uses file-based routing. Your file structure determines your site's URL structure:

docs/
├── index.md          → /
├── guide/
│   ├── index.md      → /guide/
│   └── advanced.md   → /guide/advanced
└── api/
    └── reference.md  → /api/reference

Frontmatter

Add metadata to your pages using YAML frontmatter:

markdown

---
title: Custom Page Title
description: Page description for SEO
layout: home
hero:
  name: VitePress
  text: Vite & Vue powered static site generator
  actions:
    - theme: brand
      text: Get Started
      link: /guide/
---

# Page Content

Your markdown content goes here.

Markdown Extensions

VitePress extends standard Markdown with powerful features:

Custom Containers

markdown

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

::: tip
This is a tip.
:::

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

::: danger
This is a dangerous warning.
:::

::: details Click me to view the code
```js
console.log('Hello, VitePress!')

:::


#### Code Groups

```markdown
::: code-group

```js [config.js]
export default {
  title: 'VitePress'
}

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'VitePress'
})

:::


#### Line Highlighting

```markdown
```js {2,4-6}
export default {
  title: 'VitePress', // highlighted
  description: 'Vite & Vue powered static site generator',
  themeConfig: { // highlighted
    nav: [...] // highlighted
  } // highlighted
}


## Theme Customization

### Default Theme

VitePress comes with a beautiful default theme that you can customize:

```js
// .vitepress/config.js
export default {
  themeConfig: {
    logo: '/logo.svg',
    
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      {
        text: 'Dropdown',
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' }
        ]
      }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: 'Section A',
          collapsed: false,
          items: [
            { text: 'Introduction', link: '/guide/introduction' },
            { text: 'Getting Started', link: '/guide/getting-started' }
          ]
        }
      ]
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: 'https://twitter.com/vuejs' }
    ],
    
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2024 Evan You'
    }
  }
}

Custom CSS

Override default styles with custom CSS:

css

/* .vitepress/theme/custom.css */
:root {
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
  --vp-c-brand-dark: #535bf2;
  --vp-c-brand-darker: #454ce1;
}

.custom-block {
  padding: 1rem;
  border-left: 4px solid var(--vp-c-brand);
  background-color: var(--vp-c-bg-soft);
}

Custom Theme

Create a completely custom theme:

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import CustomLayout from './CustomLayout.vue'
import './custom.css'

export default {
  extends: DefaultTheme,
  Layout: CustomLayout,
  enhanceApp({ app, router, siteData }) {
    // Register global components
    app.component('CustomComponent', CustomComponent)
  }
}

Advanced Features

Multi-language Support

Configure multiple languages:

export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    zh: {
      label: '简体中文',
      lang: 'zh-CN',
      link: '/zh/',
      themeConfig: {
        nav: [
          { text: '首页', link: '/zh/' },
          { text: '指南', link: '/zh/guide/' }
        ]
      }
    }
  }
}

Search Integration

Local Search

export default {
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        translations: {
          button: {
            buttonText: 'Search',
            buttonAriaLabel: 'Search'
          },
          modal: {
            noResultsText: 'No results found',
            resetButtonTitle: 'Reset search'
          }
        }
      }
    }
  }
}

Algolia Search

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_API_KEY',
        indexName: 'YOUR_INDEX_NAME'
      }
    }
  }
}

PWA Support

Enable Progressive Web App features:

export default {
  pwa: {
    mode: 'development',
    base: '/',
    scope: '/',
    includeAssets: ['favicon.ico'],
    manifest: {
      name: 'VitePress PWA',
      short_name: 'VitePressPWA',
      theme_color: '#ffffff',
      icons: [
        {
          src: 'pwa-192x192.png',
          sizes: '192x192',
          type: 'image/png'
        }
      ]
    }
  }
}

Vue Components in Markdown

Use Vue components directly in your Markdown files:

markdown

# My Page

<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<div class="demo">
  <button @click="count++">Count: {{ count }}</button>
</div>

<style>
.demo {
  padding: 1rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}
</style>

Regular markdown content continues here.

Global Components

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import Badge from './components/Badge.vue'
import CodeGroup from './components/CodeGroup.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('Badge', Badge)
    app.component('CodeGroup', CodeGroup)
  }
}

Then use them in any Markdown file:

markdown

# Features

- Fast <Badge type="tip" text="NEW" />
- Flexible <Badge type="warning" text="BETA" />
- Powerful <Badge type="danger" text="DEPRECATED" />

Build and Deployment

Build for Production

bash

npm run docs:build

This generates static files in docs/.vitepress/dist/.

Deployment Options

GitHub Pages

yaml

# .github/workflows/deploy.yml
name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm
          
      - name: Install dependencies
        run: npm ci
        
      - name: Build with VitePress
        run: npm run docs:build
        
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

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

Netlify

Create netlify.toml:

toml

[build]
  command = "npm run docs:build"
  publish = "docs/.vitepress/dist"

[build.environment]
  NODE_VERSION = "18"

Vercel

Create vercel.json:

json

{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vitepress/dist"
}

Performance Optimization

Bundle Analysis

bash

# Analyze bundle size
npx vitepress build docs --analyze

Code Splitting

export default {
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['vue'],
            utils: ['lodash']
          }
        }
      }
    }
  }
}

Asset Optimization

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

Best Practices

Content Organization

Use clear, descriptive file names
Organize content in logical directories
Maintain consistent navigation structure
Include comprehensive meta information

Performance

Optimize images and assets
Use code splitting for large sites
Enable compression and caching
Monitor bundle size regularly

SEO

Include proper meta tags
Generate sitemaps automatically
Use semantic HTML structure
Optimize for Core Web Vitals

Accessibility

Provide alt text for images
Ensure keyboard navigation works
Maintain proper heading hierarchy
Test with screen readers

Troubleshooting

Common Issues

Build Errors

Check Node.js version (18+)
Verify configuration syntax
Ensure all dependencies are installed

Routing Issues

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

Performance Issues

Analyze bundle size
Optimize images and assets
Review third-party dependencies

Debug Mode

bash

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

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

Migration Guide

From VuePress

Update dependencies: Replace VuePress with VitePress
Convert config: Update configuration format
Update theme: Adapt custom theme components
Test thoroughly: Verify all functionality works

From Other SSGs

Content conversion: Convert content to Markdown
Structure mapping: Map old structure to VitePress
Feature parity: Implement equivalent features
URL preservation: Set up redirects if needed

Community and Resources

Official Resources

Community

Examples

Vue.js Docs - Built with VitePress
Vite Docs - Built with VitePress
Pinia Docs - Built with VitePress

Next Steps

VitePress is actively developed and maintained by the Vue.js team. Stay updated with the latest features and improvements!

VitePress Guide ​

What is VitePress? ​

Key Features ​

Getting Started ​

Installation ​

Basic Configuration ​

Development Scripts ​

Start Development Server ​

Core Concepts ​

File-Based Routing ​

Frontmatter ​

Markdown Extensions ​

Custom Containers ​

Custom CSS ​

Custom Theme ​

Advanced Features ​

Multi-language Support ​

Search Integration ​

Local Search ​

Algolia Search ​

PWA Support ​

Vue Components in Markdown ​

Global Components ​

Build and Deployment ​

Build for Production ​

Deployment Options ​

GitHub Pages ​

Netlify ​

Vercel ​

Performance Optimization ​

Bundle Analysis ​

Code Splitting ​

Asset Optimization ​

Best Practices ​

Content Organization ​

Performance ​

SEO ​

Accessibility ​

Troubleshooting ​

Common Issues ​

Debug Mode ​

Migration Guide ​

From VuePress ​

From Other SSGs ​

Community and Resources ​

Official Resources ​

Community ​

Examples ​

Next Steps ​

VitePress Guide

What is VitePress?

Key Features

Getting Started

Installation

Basic Configuration

Development Scripts

Start Development Server

Core Concepts

File-Based Routing

Frontmatter

Markdown Extensions

Custom Containers

Custom CSS

Custom Theme

Advanced Features

Multi-language Support

Search Integration

Local Search

Algolia Search

PWA Support

Vue Components in Markdown

Global Components

Build and Deployment

Build for Production

Deployment Options

GitHub Pages

Netlify

Vercel

Performance Optimization

Bundle Analysis

Code Splitting

Asset Optimization

Best Practices

Content Organization

Performance

SEO

Accessibility

Troubleshooting

Common Issues

Debug Mode

Migration Guide

From VuePress

From Other SSGs

Community and Resources

Official Resources

Community

Examples

Next Steps