vitepress-tutorial

VitePress 源码教程生成器

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

概述

此技能可创建独立的 VitePress 教程站点，向开发者讲解代码库的内部工作原理。与说明“如何使用”的用户文档不同，这些教程会说明“如何实现”。

用法

/vitepress-tutorial [task-description]

示例：

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

工作流

阶段 1：项目分析与设置（必须首先执行）

1. 检测项目类型——识别语言、框架和 monorepo 结构
2. 询问用户偏好——使用 AskUserQuestion 工具确认：
   • 输出目录路径（根据项目结构建议合理的默认值）
   • 教程重点领域（如果任务中未指定）
   • 内容语言——要生成内容所使用的语言（请参见下文的语言选择）
3. 立即创建项目骨架——用户确认后：
   • 创建目录结构
   • 编写包含 Mermaid 插件的 package.json
   • 编写 .vitepress/config.ts
   • 编写 pnpm-workspace.yaml（如果位于另一个工作区内）
   • 运行 pnpm install

阶段 2：深入分析

1. 使用 Task 工具和 Explore Agent 探索源码目录
2. 识别关键组件、模式和架构
3. 梳理依赖关系和数据流
4. 建立模块交互的整体认知

阶段 3：生成内容

1. 根据分析结果生成所有文档文件
2. 使用 Mermaid 图表展示架构
3. 使用文件:行号注释引用实际源码
4. 构建并验证站点是否正常运行

重要指示

写入前先询问

创建任何文件前，务必使用 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

语言选择规则

• 最多 2 种语言——如果用户选择超过 2 种语言，请让他们缩小范围。并说明之后可以再次运行此技能来添加更多语言。
• 单种语言——直接在 docs/ 下生成内容，不添加语言区域前缀。相应地设置配置中的 lang。
• 两种语言——使用 VitePress i18n 和基于区域设置的目录结构：
  • 第一种选定的语言 → 根目录 /（默认区域设置）
  • 第二种选定的语言 → 添加 /{locale-code}/ 前缀
  • 在 .vitepress/config.ts 中为每种区域设置配置 locales，并设置适当的标签和导航栏/侧边栏
  • 自动在导航栏中添加语言切换器
• 语言与区域设置的对应关系：zh-CN（中文）、en-US（英语）、ja（日语）、ko（韩语）
• 内容语言只影响说明文字——无论内容语言为何，代码片段、文件路径和技术术语都保持英文

独立项目设置

在现有 pnpm 工作区内创建时，务必创建以下文件，使其保持独立：

pnpm-workspace.yaml（位于教程根目录）：

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

package.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"]
  }
}

配置 Mermaid

docs/.vitepress/config.ts（必须使用 withMermaid 包装器）：

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 依赖一个 CommonJS 模块 dayjs。如果没有此配置，Vite 开发服务器会报错：“does not provide an export named 'default'”。

安装依赖

创建项目文件后，务必运行：

cd {output-path} && pnpm install

输出结构

单种语言

{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

两种语言（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

功能

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

内容规范

1. 务必先探索——编写教程前先阅读源文件
2. 引用实际代码——附上带文件路径的真实代码片段
3. 使用 Mermaid 展示架构——可视化图表有助于理解
4. 聚焦章节内容——每个文件讲解一个概念，约 200-400 行
5. 在章节之间添加链接——使用 VitePress 上一页/下一页导航
6. 包含 API 表格——概述端点、函数和类型

辅助文件

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