Build Technical Documentation with VitePress

VitePress is a Vite-powered static site generator built specifically for technical documentation. It's the successor to VuePress and offers blazing-fast development, a clean default theme, and excellent Markdown extensibility. This guide covers deploying a VitePress documentation site on your Kazepute Breeze.

Why VitePress?

• Lightning fast: Vite's HMR provides instant feedback during development
• Vue-powered: Use Vue components directly inside Markdown
• Lightweight: Minimal JavaScript in production builds
• Built-in search: Local full-text search without external services
• Perfect for API docs: First-class support for code blocks, tabs, and badges

Quick Start

# Create project
mkdir /opt/my-docs && cd /opt/my-docs
npm init -y
npm install -D vitepress

# Initialize VitePress
npx vitepress init

# Answer the prompts:
# - Where: ./docs
# - Title: My Project Documentation
# - Description: Technical docs for My Project
# - Theme: Default Theme + Customization
# - TypeScript config: Yes

# Start dev server
npx vitepress dev docs

Configuration

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

export default defineConfig({
  title: 'My Project',
  description: 'Technical documentation',
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]],

  themeConfig: {
    logo: '/logo.svg',
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API Reference', link: '/api/' },
      { text: 'Examples', link: '/examples/' },
      {
        text: 'v3.0',
        items: [
          { text: 'v3.0 (Current)', link: '/' },
          { text: 'v2.x', link: 'https://v2.docs.yourdomain.com' },
        ],
      },
    ],

    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Introduction', link: '/guide/' },
            { text: 'Installation', link: '/guide/installation' },
            { text: 'Quick Start', link: '/guide/quick-start' },
          ],
        },
        {
          text: 'Core Concepts',
          collapsed: false,
          items: [
            { text: 'Configuration', link: '/guide/configuration' },
            { text: 'Routing', link: '/guide/routing' },
            { text: 'Deployment', link: '/guide/deployment' },
          ],
        },
      ],
    },

    socialLinks: [
      { icon: 'github', link: 'https://github.com/your-org/project' },
    ],

    search: {
      provider: 'local',
      options: {
        detailedView: true,
      },
    },

    editLink: {
      pattern: 'https://github.com/your-org/docs/edit/main/docs/:path',
      text: 'Edit this page on GitHub',
    },

    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright 2024-present Your Company',
    },
  },
})

Writing Rich Documentation

# docs/guide/installation.md
---
outline: deep
---

# Installation

## Package Managers

::: code-group
```bash [npm]
npm install my-package
```

```bash [pnpm]
pnpm add my-package
```

```bash [yarn]
yarn add my-package
```
:::

## Configuration

::: tip
Always use environment variables for sensitive configuration.
:::

::: warning
Breaking changes in v3.0 — see the [migration guide](/guide/migration).
:::

::: details Click to see the full configuration options
```ts
interface Config {
  port: number
  host: string
  database: {
    url: string
    poolSize: number
  }
}
```
:::

Build and Deploy

# Build the static site
npx vitepress build docs

# Output: docs/.vitepress/dist/

# Deploy to Nginx
sudo mkdir -p /var/www/docs
sudo cp -r docs/.vitepress/dist/* /var/www/docs/

# Nginx config
server {
    listen 443 ssl http2;
    server_name docs.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/docs.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/docs.yourdomain.com/privkey.pem;

    root /var/www/docs;
    index index.html;

    location / {
        try_files $uri $uri.html $uri/ =404;
    }

    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/html text/css application/javascript application/json;
    gzip_min_length 1000;
}

Automated Deployment Script

#!/bin/bash
# /opt/scripts/deploy-vitepress.sh
set -e

cd /opt/my-docs
git pull origin main
npm ci
npx vitepress build docs

rsync -av --delete docs/.vitepress/dist/ /var/www/docs/
echo "Deployed at $(date)"

Best Practices

• Use code groups to show commands for different package managers or platforms
• Enable local search — it works offline and requires no external services
• Structure content with sidebars using collapsible sections for large doc sets
• Add an outline (outline: deep) for automatic table of contents on each page
• Use custom Vue components for interactive demos and API explorers
• Set up CI/CD for automatic deployment on every push to the docs branch