vitepress-tutorial

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

VitePress Source Tutorial Generator

VitePress 源码教程生成工具

Generate VitePress documentation sites for source code learning and analysis.

生成用于源码学习与分析的VitePress文档站点。

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".

该工具可创建独立的VitePress教程站点，帮助开发者学习代码库的内部工作原理。这类教程不同于讲解“如何使用”的用户文档，重点在于阐述“实现机制”。

Usage

使用方法

/vitepress-tutorial [task-description]

Examples:

/vitepress-tutorial 帮我解析这个仓库的架构

/vitepress-tutorial explain the agent system in detail

/vitepress-tutorial [task-description]

示例：

/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
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)
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
```

检测项目类型 - 识别开发语言、框架、单体仓库结构
询问用户偏好 - 使用AskUserQuestion工具确认：
- 输出目录路径（根据项目结构建议合理默认值）
- 教程重点领域（若任务描述未明确说明）
- 内容语言 - 生成内容所使用的语言（详见下方“语言选择”部分）
立即创建项目骨架 - 用户确认后：
- 创建目录结构
- 编写包含Mermaid插件的
```
package.json
```
  文件
- 编写
```
.vitepress/config.ts
```
  配置文件
- 编写
```
pnpm-workspace.yaml
```
  （若处于其他工作空间内）
- 执行
```
pnpm install
```
  安装依赖

Phase 2: Deep Analysis

阶段2：深度分析

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

使用Task工具结合Explore Agent探索源码目录
识别核心组件、设计模式与整体架构
梳理依赖关系与数据流
构建模块交互的心智模型

Phase 3: Content Generation

阶段3：内容生成

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

根据分析结果生成所有文档文件
加入Mermaid图表实现架构可视化
通过“文件:行号”标注引用真实源码
构建站点并验证功能正常

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

在创建任何文件前，必须使用AskUserQuestion工具确认输出位置和内容语言。

在一次AskUserQuestion调用中提出两个问题：

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

最多支持2种语言 - 若用户选择超过2种，需请其缩减范围。告知用户可后续再次运行该工具添加更多语言。
单语言模式 - 内容直接生成在
```
docs/
```
目录下，无需区域前缀。在配置文件中对应设置
```
lang
```
参数。
双语言模式 - 采用VitePress的i18n功能，基于区域目录结构组织内容：
- 首个选中语言 → 根目录
```
/
```
  （默认区域）
- 第二个选中语言 →
```
/{locale-code}/
```
  前缀
- 在
```
.vitepress/config.ts
```
  中配置
```
locales
```
  ，为每个区域设置合适的标签、导航栏与侧边栏
- 自动在导航栏添加语言切换器
语言与区域映射:
```
zh-CN
```
（中文）、
```
en-US
```
（英文）、
```
ja
```
（日文）、
```
ko
```
（韩文）
内容语言仅影响正文描述 - 代码片段、文件路径与技术术语始终保持英文，不受内容语言影响

Standalone Project Setup

独立项目配置

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

pnpm-workspace.yaml (in tutorial root):

yaml

undefined

当在已有的pnpm工作空间内创建时，必须生成以下文件以保证独立性：

pnpm-workspace.yaml (in tutorial root):

yaml

undefined

Independent workspace - prevents inheriting parent config

packages: []


**package.json** (MUST include):
```json
{
  "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"]
  }
}

packages: []


**package.json** (MUST include):
```json
{
  "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

集成Mermaid的配置

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

typescript

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.

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

typescript

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'
  }
}))

为什么需要
vite.optimizeDeps
？ Mermaid依赖的dayjs是一个CommonJS模块。若无此配置，Vite开发服务器会抛出“does not provide an export named 'default'”错误。

Install Dependencies

安装依赖

After creating project files, ALWAYS run:

bash

cd {output-path} && pnpm install

创建项目文件后，必须执行以下命令：

bash

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

{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)

双语言结构（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

{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

Mermaid图表：支持架构图、时序图与流程图（自动安装）
源码引用：自动生成
```
Source: path/to/file.go:123
```
格式的标注
代码高亮：支持Go、TypeScript、Python语言及行高亮
多语言支持：每次运行最多选择2种语言（中文、英文、日文、韩文），后续可再次运行添加更多语言
独立部署：可直接部署至Vercel、Netlify或GitHub Pages

Content Guidelines

内容规范

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

先探索再编写 - 编写教程前需先阅读源码文件
引用真实代码 - 包含带文件路径的真实代码片段
用Mermaid展示架构 - 可视化图表有助于理解
章节聚焦主题 - 每个文件讲解一个概念，篇幅约200-400行
章节间关联 - 利用VitePress的上一页/下一页导航功能
添加API表格 - 汇总接口、函数与类型信息

Supporting Files

支持文件

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

@config-template.md - VitePress配置模板
@project-structure.md - 项目结构与文件模板
@content-guidelines.md - 内容编写规范