vitepress-tutorial

VitePress ソースチュートリアル生成ツール

ソースコードの学習と分析に役立つ VitePress ドキュメントサイトを生成します。

概要

このスキルは、コードベースの内部の仕組みを開発者に解説する、独立した VitePress チュートリアルサイトを作成します。「使い方」を説明するユーザードキュメントとは異なり、「どのように実装されているか」を解説します。

使用方法

/vitepress-tutorial [task-description]

例：

• /vitepress-tutorial このリポジトリのアーキテクチャを分析してください
• /vitepress-tutorial エージェントシステムを詳しく解説してください

ワークフロー

フェーズ 1：プロジェクトの分析とセットアップ（最初に必ず実施）

1. プロジェクトの種類を検出する - 言語、フレームワーク、モノレポ構造を特定します
2. ユーザーに希望を確認する - AskUserQuestion ツールを使って、以下を確認します：
   • 出力ディレクトリのパス（プロジェクト構造に基づいて妥当なデフォルトを提案します）
   • チュートリアルで扱う領域（タスク内で指定されていない場合）
   • コンテンツの言語 - コンテンツを生成する言語（複数可）（下記の「言語の選択」を参照）
3. すぐにプロジェクトの骨組みを作成する - ユーザーの確認後：
   • ディレクトリ構造を作成します
   • Mermaid プラグインを含む package.json を作成します
   • .vitepress/config.ts を作成します
   • （別のワークスペース内に作成する場合）pnpm-workspace.yaml を作成します
   • pnpm install を実行します

フェーズ 2：詳細な分析

1. Task ツールと Explore エージェントを使ってソースディレクトリを調査します
2. 主要なコンポーネント、パターン、アーキテクチャを特定します
3. 依存関係とデータフローを整理します
4. モジュール間の相互作用について全体像を把握します

フェーズ 3：コンテンツの生成

1. 分析結果に基づいて、すべてのドキュメントファイルを生成します
2. アーキテクチャを視覚化する Mermaid 図を含めます
3. 実際のソースコードをファイル名と行番号の注記付きで参照します
4. サイトをビルドし、正常に動作することを確認します

重要な指示

書き込み前に確認する

ファイルを作成する前に、必ず AskUserQuestion を使って出力先と言語を確認してください。

1 回の AskUserQuestion 呼び出しで、次の 2 つの質問をしてください。

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 を適切に指定します。
• 2 言語 - VitePress の i18n とロケール別のディレクトリ構造を使用します：
  • 1 つ目に選択した言語 → ルート /（デフォルトロケール）
  • 2 つ目に選択した言語 → /{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

2 言語（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（行のハイライト対応）
• 多言語サポート：1 回の実行につき最大 2 言語（中国語、英語、日本語、韓国語）を選択できます。後から再度実行して、言語を追加できます。
• 単独デプロイ：Vercel、Netlify、GitHub Pages にすぐにデプロイできます

コンテンツのガイドライン

1. まず必ず調査する - チュートリアルを書く前にソースファイルを読む
2. 実際のコードを参照する - ファイルパスを含む実際のコードスニペットを記載する
3. アーキテクチャにはMermaidを使用する - 視覚的な図は理解に役立つ
4. 各章のテーマを絞る - 1つのファイルにつき1つの概念とし、約200～400行にまとめる
5. 各章を相互にリンクする - VitePressの前へ／次へナビゲーションを使用する
6. APIテーブルを含める - エンドポイント、関数、型を要約する

補足ファイル

• @config-template.md - VitePress設定テンプレート
• @project-structure.md - プロジェクト構成とファイルテンプレート
• @content-guidelines.md - コンテンツ作成ガイドライン