Vitepress Tutorial

VitePress Source Tutorial Generator

Generate VitePress documentation sites for source code learning and analysis.

Overview

This skill creates standalone VitePress tutorial sites that teach developers how a codebase works internally. Unlike user documentation that explains "how to use", these tutorials explain "how it's implemented".

Usage

/vitepress-tutorial [task-description]

Examples:

• /vitepress-tutorial 帮我解析这个仓库的架构
• /vitepress-tutorial explain the agent system in detail

Workflow

Phase 1: Project Analysis & Setup (REQUIRED FIRST)

1. Detect project type - Identify language, framework, monorepo structure 2. Ask user for preferences - Use AskUserQuestion tool to confirm:

• Output directory path (suggest reasonable default based on project structure)
• Tutorial focus areas (if not specified in the task)
• Content language(s) - Which language(s) to generate content in (see Language Selection below)

3. Create project skeleton immediately - After user confirms:

• Create directory structure
• Write package.json with Mermaid plugin
• Write .vitepress/config.ts
• Write pnpm-workspace.yaml (if inside another workspace)
• Run pnpm install

Phase 2: Deep Analysis

1. Explore source directory using Task tool with Explore agent 2. Identify key components, patterns, and architecture 3. Map dependencies and data flows 4. Build mental model of module interactions

Phase 3: Content Generation

1. Generate all documentation files based on analysis 2. Include Mermaid diagrams for architecture visualization 3. Reference actual source code with file:line annotations 4. Build and verify the site works

CRITICAL INSTRUCTIONS

Ask Before Writing

ALWAYS use AskUserQuestion to confirm output location AND content language before creating any files.

Use two questions in one AskUserQuestion call:

Question 1: "Where should I create the VitePress tutorial site?"
Options:
- "./docs" (project docs folder)
- "./tutorials/{project-name}" (dedicated tutorials folder)
- Custom path...

Question 2: "What language(s) should the tutorial content be written in? (Max 2)"
multiSelect: true
Options:
- "中文 (Chinese)" - Content in Chinese, code comments in English
- "English" - Content and code comments in English
- "日本語 (Japanese)" - Content in Japanese, code comments in English
- "한국어 (Korean)" - Content in Korean, code comments in English

Language Selection Rules

• Max 2 languages - If user selects more than 2, ask them to narrow down. Mention they can run the skill again later to add more languages.
• Single language - Generate content directly under docs/ with no locale prefix. Set lang in config accordingly.
• Two languages - Use VitePress i18n with locale-based directory structure:
• First selected language → root / (default locale)
• Second selected language → /{locale-code}/ prefix
• Configure locales in .vitepress/config.ts with proper labels and nav/sidebar for each locale
• Add language switcher in navbar automatically
• Language-to-locale mapping: zh-CN (Chinese), en-US (English), ja (Japanese), ko (Korean)
• Content language only affects prose - Code snippets, file paths, and technical terms stay in English regardless of content language

Standalone Project Setup

When creating inside an existing pnpm workspace, ALWAYS create these files to make it independent:

pnpm-workspace.yaml (in tutorial root):

# Independent workspace - prevents inheriting parent config
packages: []

package.json (MUST include):

{
  "name": "{tutorial-name}",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  },
  "devDependencies": {
    "mermaid": "^11.4.0",
    "vitepress": "^1.6.3",
    "vitepress-plugin-mermaid": "^2.0.17"
  },
  "pnpm": {
    "onlyBuiltDependencies": ["esbuild"]
  }
}

Config with Mermaid

docs/.vitepress/config.ts (MUST use withMermaid wrapper):

import { defineConfig } from 'vitepress'
import { withMermaid } from 'vitepress-plugin-mermaid'

export default withMermaid(defineConfig({
  // CRITICAL: Fix Mermaid's dayjs ESM compatibility issue
  vite: {
    optimizeDeps: {
      include: ['mermaid', 'dayjs']
    }
  },
  // ... rest of config
  mermaid: {
    theme: 'default'
  }
}))

Why `vite.optimizeDeps`? Mermaid depends on dayjs which is a CommonJS module. Without this config, Vite dev server will throw "does not provide an export named 'default'" error.

Install Dependencies

After creating project files, ALWAYS run:

cd {output-path} && pnpm install

Output Structure

Single Language

{output-path}/
├── package.json              # With mermaid plugin
├── pnpm-workspace.yaml       # If inside another workspace
├── README.md
└── docs/
    ├── .vitepress/
    │   └── config.ts         # With withMermaid wrapper
    ├── index.md              # Homepage
    ├── introduction/
    │   ├── overview.md       # Project overview
    │   └── architecture.md   # Architecture diagram
    └── {modules}/            # One directory per module
        ├── index.md
        └── {topics}.md

Two Languages (i18n)

{output-path}/
├── package.json
├── pnpm-workspace.yaml
├── README.md
└── docs/
    ├── .vitepress/
    │   └── config.ts         # With locales config + withMermaid
    ├── index.md              # Default locale homepage
    ├── introduction/         # Default locale content
    │   ├── overview.md
    │   └── architecture.md
    ├── {modules}/
    │   ├── index.md
    │   └── {topics}.md
    └── {locale}/             # e.g. "en" or "zh"
        ├── index.md          # Second locale homepage
        ├── introduction/
        │   ├── overview.md
        │   └── architecture.md
        └── {modules}/
            ├── index.md
            └── {topics}.md

Features

• Mermaid Diagrams: Architecture, sequence, and flow diagrams (auto-installed)
• Source References: Auto-generate Source: path/to/file.go:123 annotations
• Code Highlighting: Go, TypeScript, Python with line highlighting
• Multi-language Support: Choose up to 2 languages per run (Chinese, English, Japanese, Korean). Run again to add more languages later.
• Standalone Deploy: Ready for Vercel, Netlify, or GitHub Pages

Content Guidelines

1. Always explore first - Read source files before writing tutorials 2. Reference actual code - Include real code snippets with file paths 3. Use Mermaid for architecture - Visual diagrams aid understanding 4. Keep chapters focused - One concept per file, ~200-400 lines 5. Link between chapters - Use VitePress prev/next navigation 6. Include API tables - Summarize endpoints, functions, types

Supporting Files

• @config-template.md - VitePress configuration template
• @project-structure.md - Project structure and file templates
• @content-guidelines.md - Content writing guidelines

VitePress Configuration Template

docs/.vitepress/config.ts

import { defineConfig } from 'vitepress'
import { withMermaid } from 'vitepress-plugin-mermaid'

export default withMermaid(defineConfig({
  // CRITICAL: Vite optimization for Mermaid's CJS dependencies (dayjs)
  // Without this, you'll get ESM import errors in dev mode
  vite: {
    optimizeDeps: {
      include: ['mermaid', 'dayjs']
    }
  },

  // Site metadata - set lang based on user's selected default language
  title: '{Project Title}',
  description: '{Project description}',
  lang: '{locale-code}',  // e.g. 'zh-CN', 'en-US', 'ja', 'ko'

  // Build output
  outDir: '../dist',

  // Theme configuration
  themeConfig: {
    // Navigation bar
    nav: [
      { text: 'Home', link: '/' },
      { text: '{Module 1}', link: '/{module1}/' },
      { text: '{Module 2}', link: '/{module2}/' },
      {
        text: 'Resources',
        items: [
          { text: 'Official Docs', link: '{official-docs-url}' },
          { text: 'GitHub', link: '{github-url}' }
        ]
      }
    ],

    // Sidebar configuration
    sidebar: {
      '/': [
        {
          text: 'Introduction',
          items: [
            { text: 'Overview', link: '/introduction/overview' },
            { text: 'Architecture', link: '/introduction/architecture' }
          ]
        },
        {
          text: '{Module 1}',
          items: [
            { text: 'Overview', link: '/{module1}/' },
            { text: '{Topic 1}', link: '/{module1}/{topic1}' },
            { text: '{Topic 2}', link: '/{module1}/{topic2}' },
            { text: '{Topic 3}', link: '/{module1}/{topic3}' }
          ]
        },
        {
          text: '{Module 2}',
          items: [
            { text: 'Overview', link: '/{module2}/' },
            { text: '{Topic 1}', link: '/{module2}/{topic1}' },
            { text: '{Topic 2}', link: '/{module2}/{topic2}' }
          ]
        }
      ]
    },

    // Social links
    socialLinks: [
      { icon: 'github', link: '{github-url}' }
    ],

    // Search
    search: {
      provider: 'local',
      options: {
        translations: {
          button: {
            buttonText: 'Search',
            buttonAriaLabel: 'Search'
          },
          modal: {
            noResultsText: 'No results',
            resetButtonTitle: 'Clear',
            footer: {
              selectText: 'Select',
              navigateText: 'Navigate',
              closeText: 'Close'
            }
          }
        }
      }
    },

    // Footer
    footer: {
      message: '{Footer message}',
      copyright: 'MIT License'
    },

    // Edit link (optional)
    editLink: {
      pattern: '{github-url}/edit/main/docs/:path',
      text: 'Edit this page'
    },

    // Last updated
    lastUpdated: {
      text: 'Last updated',
      formatOptions: {
        dateStyle: 'short',
        timeStyle: 'short'
      }
    },

    // Outline
    outline: {
      level: [2, 3],
      label: 'Table of Contents'
    },

    // Doc footer navigation
    docFooter: {
      prev: 'Previous',
      next: 'Next'
    }
  },

  // Markdown configuration
  markdown: {
    // Enable line numbers in code blocks
    lineNumbers: true,

    // Code block themes
    theme: {
      light: 'github-light',
      dark: 'github-dark'
    }
  },

  // Mermaid configuration
  mermaid: {
    // Mermaid options: https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults
    theme: 'default'
  },

  // Optional: customize mermaid plugin options
  mermaidPlugin: {
    class: 'mermaid'
  },

  // Head tags
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }],
    ['meta', { name: 'theme-color', content: '#3c8772' }]
  ],

  // Sitemap (for SEO)
  sitemap: {
    hostname: '{site-url}'
  }
}))

i18n Configuration (Two Languages)

When user selects 2 languages, add locales to the config. The first selected language is the root locale, the second gets a path prefix.

export default withMermaid(defineConfig({
  // ... vite, mermaid config same as above

  locales: {
    // Root locale (first selected language)
    root: {
      label: '{Language Label}',  // e.g. '中文', 'English'
      lang: '{locale-code}',     // e.g. 'zh-CN', 'en-US'
      title: '{Project Title}',
      description: '{Description}',
      themeConfig: {
        nav: [/* localized nav */],
        sidebar: {/* localized sidebar */},
        outline: { label: '{localized}' },
        docFooter: { prev: '{localized}', next: '{localized}' },
      }
    },
    // Second locale
    '{locale-path}': {  // e.g. 'en', 'zh', 'ja', 'ko'
      label: '{Language Label}',
      lang: '{locale-code}',
      title: '{Project Title}',
      description: '{Description}',
      themeConfig: {
        nav: [/* localized nav */],
        sidebar: {/* localized sidebar with /{locale-path}/ prefix in links */},
        outline: { label: '{localized}' },
        docFooter: { prev: '{localized}', next: '{localized}' },
      }
    }
  },

  themeConfig: {
    // Shared config (socialLinks, search, etc.)
    socialLinks: [
      { icon: 'github', link: '{github-url}' }
    ],
    search: { provider: 'local' },
  }
}))

Locale UI Labels Reference

Configuration Variables

Sidebar Patterns

Flat Structure

sidebar: [
  { text: 'Page 1', link: '/page1' },
  { text: 'Page 2', link: '/page2' }
]

Grouped Structure

sidebar: [
  {
    text: 'Group',
    collapsed: false,  // false = expanded by default
    items: [
      { text: 'Item 1', link: '/group/item1' },
      { text: 'Item 2', link: '/group/item2' }
    ]
  }
]

Multi-Sidebar (different sidebars for different paths)

sidebar: {
  '/module1/': [/* module1 sidebar */],
  '/module2/': [/* module2 sidebar */],
  '/': [/* default sidebar */]
}

Deployment Configuration

Vercel

No additional configuration needed. Vercel auto-detects VitePress.

GitHub Pages

Add to config.ts:

export default defineConfig({
  base: '/{repo-name}/',  // If deploying to github.io/{repo-name}
  // ...
})

Netlify

Create netlify.toml:

[build]
  command = "pnpm build"
  publish = "docs/.vitepress/dist"

Content Writing Guidelines

Core Principles

1. Explain "How", not "What to do" - Focus on implementation details, not usage instructions 2. Reference Real Code - Always include actual source file paths and line numbers 3. Visual First - Use Mermaid diagrams before lengthy text explanations 4. Progressive Depth - Start with overview, then dive into details

Chapter Structure

Standard Chapter Template

---
outline: [2, 3]
prev:
  text: 'Previous Chapter'
  link: '/module/prev'
next:
  text: 'Next Chapter'
  link: '/module/next'
---

# Chapter Title

Brief introduction (2-3 sentences) explaining what this chapter covers.

## Overview Diagram

\`\`\`mermaid
flowchart TD
    A[Step 1] --> B[Step 2]
    B --> C[Step 3]
\`\`\`

## Source Location

\`\`\`
path/to/source/
├── file1.go      # Description
├── file2.go      # Description
└── subdir/
    └── file3.go  # Description
\`\`\`

## Core Concept 1

**Source**: `path/to/file.go`

Explanation of the concept.

\`\`\`go
// path/to/file.go

func ExampleFunction() {
    // Key implementation
}
\`\`\`

### Sub-topic

More detailed explanation with code.

## Core Concept 2

...

## Summary

- **Point 1** - Brief recap
- **Point 2** - Brief recap
- **Point 3** - Brief recap

Next chapter: [Next Topic](/module/next)

Source Code References

Inline Reference

The `CreateSandbox` function in `apps/runner/pkg/docker/create.go` handles...

Block Reference

**Source**: `apps/runner/pkg/docker/create.go`

\`\`\`go
// apps/runner/pkg/docker/create.go

func (d *DockerClient) CreateSandbox(ctx context.Context, opts CreateOptions) error {
    // Implementation
}
\`\`\`

With Line Numbers

**Source**: `apps/runner/pkg/docker/create.go:45-67`

Mermaid Diagram Patterns

Architecture Diagram

\`\`\`mermaid
flowchart TD
    subgraph External
        Client[SDK Client]
    end

    subgraph Internal
        API[API Server]
        Worker[Worker]
        DB[(Database)]
    end

    Client --> API
    API --> Worker
    Worker --> DB
\`\`\`

Sequence Diagram

\`\`\`mermaid
sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Database

    C->>A: Request
    A->>D: Query
    D-->>A: Result
    A-->>C: Response
\`\`\`

State Diagram

\`\`\`mermaid
stateDiagram-v2
    [*] --> Creating
    Creating --> Started: success
    Creating --> Error: failure
    Started --> Stopped: stop
    Stopped --> Started: start
    Stopped --> [*]: destroy
\`\`\`

Flowchart with Decision

\`\`\`mermaid
flowchart TD
    A[Start] --> B{Condition?}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
\`\`\`

Tables

API Endpoint Table

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/sandboxes` | POST | Create sandbox |
| `/sandboxes/{id}` | GET | Get sandbox |
| `/sandboxes/{id}` | DELETE | Delete sandbox |

Data Structure Table

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier |
| `status` | `enum` | Current state |
| `createdAt` | `time.Time` | Creation timestamp |

Comparison Table

| Aspect | Option A | Option B |
|--------|----------|----------|
| Performance | Fast | Slower |
| Complexity | High | Low |
| Use Case | Production | Development |

Code Block Best Practices

Language Specification

\`\`\`go
// Go code
\`\`\`

\`\`\`typescript
// TypeScript code
\`\`\`

\`\`\`bash
# Shell commands
\`\`\`

\`\`\`json
{
  "json": "data"
}
\`\`\`

Highlighting Key Lines

\`\`\`go{3-5}
func Example() {
    // Normal line
    // Highlighted line 1
    // Highlighted line 2
    // Highlighted line 3
    // Normal line
}
\`\`\`

Simplified Code

When showing implementation patterns, simplify error handling:

\`\`\`go
// Simplified - error handling omitted for clarity
result, _ := doSomething()
\`\`\`

Writing Style

Language

• Content: Write in the language(s) selected by the user during setup
• Code comments: Always in English, regardless of content language
• Technical terms: Keep in English (API, Docker, Daemon, etc.)
• When generating two languages: Produce the same content structure for both locales — same diagrams, same code blocks, only prose translated

Tone

• Direct and technical
• Avoid marketing language
• Assume reader has programming experience

Length Guidelines

• Chapter: 200-400 lines
• Section: 50-100 lines
• Paragraph: 3-5 sentences
• Code blocks: 10-30 lines (simplify if longer)

Navigation

Chapter Ordering

1. Overview/Introduction first 2. Core concepts in logical order 3. Advanced topics last 4. Summary/Conclusion at end

Cross-References

See [Lifecycle Management](/sandbox/lifecycle) for details.

As discussed in the [Architecture](/introduction/architecture) chapter...

Callouts (Custom Containers)

::: tip
Helpful tip here.
:::

::: warning
Important warning.
:::

::: danger
Critical information.
:::

::: info
Additional context.
:::

Content Checklist

Before completing a chapter:

• [ ] Frontmatter with prev/next links
• [ ] Source file paths included
• [ ] At least one Mermaid diagram
• [ ] Code blocks have language specified
• [ ] Summary section at end
• [ ] No orphan links
• [ ] Content in user's selected language(s), code comments in English

Project Structure Template

Directory Layout

Single Language

{project-name}/
├── package.json
├── pnpm-workspace.yaml       # REQUIRED if inside another pnpm workspace
├── README.md
├── .gitignore
└── docs/
    ├── .vitepress/
    │   └── config.ts
    ├── index.md
    ├── introduction/
    │   ├── overview.md
    │   └── architecture.md
    └── {module}/
        ├── index.md
        └── {topic}.md

Two Languages (i18n)

{project-name}/
├── package.json
├── pnpm-workspace.yaml
├── README.md
├── .gitignore
└── docs/
    ├── .vitepress/
    │   └── config.ts          # With locales config
    ├── index.md               # Default locale homepage
    ├── introduction/          # Default locale content
    │   ├── overview.md
    │   └── architecture.md
    ├── {module}/
    │   ├── index.md
    │   └── {topic}.md
    └── {locale}/              # Second locale (e.g. "en", "zh", "ja", "ko")
        ├── index.md
        ├── introduction/
        │   ├── overview.md
        │   └── architecture.md
        └── {module}/
            ├── index.md
            └── {topic}.md

pnpm-workspace.yaml

CRITICAL: When creating inside an existing pnpm workspace, ALWAYS create this file to make the tutorial project independent:

# Independent workspace - prevents inheriting parent config
packages: []

This prevents pnpm from inheriting the parent workspace configuration, which can cause ESM compatibility issues with VitePress.

package.json

{
  "name": "{project-name}",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  },
  "devDependencies": {
    "mermaid": "^11.4.0",
    "vitepress": "^1.6.3",
    "vitepress-plugin-mermaid": "^2.0.17"
  },
  "pnpm": {
    "onlyBuiltDependencies": ["esbuild"]
  }
}

Important notes:

• "type": "module" is REQUIRED for VitePress ESM compatibility
• pnpm.onlyBuiltDependencies prevents unnecessary native module builds

.gitignore

node_modules/
dist/
.vitepress/cache/
.vitepress/dist/
*.local
.DS_Store

README.md Template

# {Project Title}

{Brief description of what this tutorial covers}

## About

This tutorial focuses on source code learning:

- **Official docs** → How to use {project}
- **This tutorial** → How {project} is implemented

### Content Overview

- **{Module 1} Source Analysis**
  - {Topic 1}
  - {Topic 2}

- **{Module 2} Source Analysis**
  - {Topic 1}
  - {Topic 2}

## Development

\`\`\`bash
# Install dependencies
pnpm install

# Local development
pnpm dev

# Build
pnpm build

# Preview build
pnpm preview
\`\`\`

## Deployment

Static files can be deployed to any hosting platform:

- GitHub Pages
- Vercel
- Netlify

## Related Links

- [Official Documentation]({official-docs-url})
- [GitHub Repository]({github-url})

## License

MIT

docs/index.md Template

---
layout: home
hero:
  name: "{Project Title}"
  text: "{Tagline}"
  tagline: "{Description}"
  actions:
    - theme: brand
      text: Start Learning
      link: /introduction/overview
    - theme: alt
      text: View on GitHub
      link: {github-url}

features:
  - icon: 📦
    title: {Module 1}
    details: {Module 1 description}
  - icon: 🤖
    title: {Module 2}
    details: {Module 2 description}
  - icon: 🔧
    title: {Module 3}
    details: {Module 3 description}
---

Chapter Frontmatter Template

---
outline: [2, 3]
prev:
  text: '{Previous Chapter}'
  link: '/{module}/{prev-topic}'
next:
  text: '{Next Chapter}'
  link: '/{module}/{next-topic}'
---

Module Index Template

---
outline: [2, 3]
---

# {Module Name} Overview

Brief introduction to this module.

## Source Location

\`\`\`
{source-path}/
├── {file1}.go
├── {file2}.go
└── {subdir}/
    └── {file3}.go
\`\`\`

## Core Concepts

| Concept | Description | Source |
|---------|-------------|--------|
| {Concept1} | {Description} | `{path}` |
| {Concept2} | {Description} | `{path}` |

## Architecture

\`\`\`mermaid
flowchart TD
    A[Component A] --> B[Component B]
    B --> C[Component C]
\`\`\`

## Chapters

1. [{Topic 1}](./{topic1}) - {Brief description}
2. [{Topic 2}](./{topic2}) - {Brief description}
3. [{Topic 3}](./{topic3}) - {Brief description}