Skip to content

Commit 02ff0c3

Browse files
CheShipingCheShiping
committed
"add-vitepress-skill"
1 parent 8177f3a commit 02ff0c3

5 files changed

Lines changed: 393 additions & 0 deletions

File tree

‎.codebuddy/skills/vitepress-docs-deploy/SKILL.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
name: vitepress-docs-deploy
3+
description: >
4+
This skill converts markdown tutorial/documentation files into a beautiful,
5+
searchable VitePress documentation site and deploys it to GitHub Pages.
6+
It should be used when the user wants to publish markdown-based tutorials,
7+
guides, or documentation as an online site integrated with a GitHub repository.
8+
Triggers include phrases like "make my tutorial online", "publish my docs",
9+
"create a documentation site from markdown", "deploy to GitHub Pages with VitePress",
10+
or "I want my notes accessible as a website".
11+
---
12+
13+
# VitePress GitHub Pages 文档部署
14+
15+
## 概述
16+
17+
将一组 markdown 教程/文档文件转换为一
18+
个功能完备的 VitePress 文档网站，并通过 GitHub Actions 自动化部署到 GitHub Pages。最终提供一个带侧边栏导航、全文搜索、暗色模式、Mermaid 图表支持的在线文档站点。
19+
20+
## 工作流程
21+
22+
### Step 1: 理解源文件结构
23+
24+
首先，列出教程 markdown 目录的内容，确定：
25+
- 有哪些章节目录（part1, part2, ...）
26+
- 每个目录下的 markdown 文件名称和顺序
27+
- 是否有附录、图片、代码示例等附加资源
28+
29+
使用 `list_files` 获取完整结构。
30+
31+
### Step 2: 迁移文件到 `docs/` 目录
32+
33+
将所有教程 markdown 文件移动到项目根目录下的 `docs/` 文件夹内。
34+
35+
1. 创建 `docs/` 目录
36+
2. 将章节目录移动到 `docs/` 下，使用简洁的英文命名：
37+
- `part1-xxx/` → `docs/xxx/`
38+
- `part2-xxx/` → `docs/yyy/`
39+
- `part3-xxx/` → `docs/zzz/`
40+
- `appendix/` → `docs/appendix/`
41+
3. 同步复制 `images/`、`code-examples/` 等资源目录到 `docs/`
42+
4. 保留原 `deep_research-tutorial/` 中的 `README.md`（作为 GitHub 仓库主页），但根据实际情况可移除或以 `docs/README.md` 引用
43+
44+
使用 `move` 命令移动章节目录，使用 `xcopy` 复制资源目录。
45+
46+
### Step 3: 创建 `docs/package.json`
47+
48+
在 `docs/` 目录下创建 VitePress Node 项目配置。
49+
50+
参考资产文件 `assets/package.json.template`，替换其中的 `name` 字段为项目名称。
51+
52+
关键依赖：
53+
- `vitepress` - 核心框架
54+
- `mermaid` + `vitepress-plugin-mermaid` - 图表渲染支持（如果源文件中使用了 mermaid 代码块）
55+
56+
### Step 4: 创建 `.vitepress/config.mts`
57+
58+
这是 VitePress 的核心配置文件。参考 `assets/config.mts.template`，根据项目实际情况修改以下内容：
59+
60+
1. **项目元数据**：`title`、`description`、`lang`
61+
2. **base 路径**：`base: '/<repo-name>/'`（GitHub Pages 子路径部署必需）
62+
3. **侧边栏导航**：为每个章节目录配置 sidebar，结构与 Step 1 中分析的一致
63+
4. **导航栏**：首页链接、章节入口、源码链接
64+
5. **搜索**：`provider: 'local'` - 中文文档需翻译搜索界面文本
65+
6. **页脚、编辑链接、最后更新**等辅助功能
66+
7. **社交链接**：指向 GitHub 仓库
67+
68+
**重要**：`base` 必须与 GitHub 仓库名完全一致（区分大小写），格式为 `/<repo-name>/`。
69+
70+
### Step 5: 创建首页 `docs/index.md`
71+
72+
创建 VitePress 首页，使用 `layout: home` 布局。
73+
74+
参考 `assets/index.md.template`，包含：
75+
- **hero** 区域：项目名称、标语、行动按钮
76+
- **features** 区域：特性卡片（图标 + 标题 + 描述 + 链接）
77+
- **章节概览**：3个 Part 的简要介绍
78+
- **技术栈表** 和 **学习路径**
79+
80+
所有内部链接需要与 `config.mts` 中的 sidebar 配置对齐。
81+
82+
### Step 6: 修复 Markdown 死链接
83+
84+
源 markdown 文件中可能存在指向旧路径的链接（如 `../README.md`），需要修复为 VitePress 路由路径。
85+
86+
1. 使用 `vitepress build` 构建检查死链接
87+
2. 根据报错信息逐一修复
88+
3. 将路径改为 VitePress 兼容格式（如 `/` 代替 `../README.md`）
89+
90+
### Step 7: 创建 GitHub Actions 部署工作流
91+
92+
在 `.github/workflows/deploy-docs.yml` 创建自动部署配置。
93+
94+
参考 `assets/deploy-docs.yml.template`，工作流包含：
95+
1. **触发条件**：push 到主分支且 `docs/**` 路径变更，支持手动触发
96+
2. **构建任务**：checkout → 设置 Node.js 22 → 配置 Pages → 安装依赖 → 构建
97+
3. **部署任务**：将 `docs/.vitepress/dist` 产出部署到 GitHub Pages
98+
99+
注意：
100+
- Node.js 版本设置为 `22`（GitHub Actions 已弃用 Node 20）
101+
- `configure-pages@v5` 使用 `enablement: true` 自动启用 Pages
102+
- 使用 `upload-pages-artifact@v3` 上传构建产物
103+
104+
### Step 8: 更新 `.gitignore`
105+
106+
在项目根目录 `.gitignore` 中追加 VitePress 相关忽略项：
107+
108+
```
109+
# VitePress
110+
docs/.vitepress/dist/
111+
docs/.vitepress/cache/
112+
```
113+
114+
### Step 9: 构建验证
115+
116+
在 `docs/` 目录下执行：
117+
```bash
118+
npm install && npm run build
119+
```
120+
121+
确认构建成功无报错后，删除 `node_modules/` 和 `.vitepress/dist/`（它们不应提交到仓库）。
122+
123+
### Step 10: 提交并推送
124+
125+
```bash
126+
git add .
127+
git commit -m "docs: add VitePress documentation site with GitHub Pages deployment"
128+
git push
129+
```
130+
131+
### Step 11: 部署后指引
132+
133+
推送完成后，告知用户：
134+
135+
1. GitHub Actions 将自动构建部署
136+
2. 如果 `configure-pages@v5` 的 `enablement: true` 未生效，用户需手动进入 `Settings → Pages`，将 Source 设为 `GitHub Actions`
137+
3. 网站地址格式：`https://<username>.github.io/<repo-name>/`
138+
4. 后续每次推送 `docs/` 目录变更即自动更新
139+
140+
### Step 12: 问题排查
141+
142+
常见问题及解决方案：
143+
144+
| 问题 | 原因 | 解决 |
145+
|------|------|------|
146+
| CSS/样式丢失 | 未配置 `base` | 在 `config.mts` 添加 `base: '/<repo>/'` |
147+
| 死链接报错 | 旧路径不兼容 | 改为 VitePress 路由路径 |
148+
| Mermaid 图表不渲染 | 缺少插件 | 安装 `mermaid` + `vitepress-plugin-mermaid` |
149+
| HttpError: Not Found | Pages 未启用 | Settings → Pages → GitHub Actions |
150+
| Node 20 deprecated | 旧版本 Node | 升级到 Node 22 |
151+
152+
## 资产文件
153+
154+
- `assets/package.json.template` - VitePress 项目配置模板
155+
- `assets/config.mts.template` - VitePress 配置模板
156+
- `assets/deploy-docs.yml.template` - GitHub Actions 工作流模板
157+
- `assets/index.md.template` - 首页模板

‎.codebuddy/skills/vitepress-docs-deploy/assets/config.mts.template‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
import { defineConfig } from 'vitepress'
2+
import { withMermaid } from 'vitepress-plugin-mermaid'
3+
4+
export default withMermaid(
5+
defineConfig({
6+
title: 'PROJECT_TITLE',
7+
description: 'PROJECT_DESCRIPTION',
8+
lang: 'zh-CN',
9+
// IMPORTANT: must match GitHub repo name exactly with leading/trailing slashes
10+
base: '/REPO_NAME/',
11+
12+
head: [
13+
['link', { rel: 'icon', href: '/favicon.ico' }],
14+
],
15+
16+
themeConfig: {
17+
// Navigation bar
18+
nav: [
19+
{ text: '首页', link: '/' },
20+
{ text: '教程', link: '/chapter-1/01-intro' },
21+
{
22+
text: '项目源码',
23+
items: [
24+
{ text: 'GitHub 仓库', link: 'https://github.com/USER/REPO' },
25+
]
26+
},
27+
],
28+
29+
// Sidebar - configure per chapter
30+
sidebar: {
31+
'/chapter-1/': [
32+
{
33+
text: '第一章标题',
34+
items: [
35+
{ text: '1. 章节名', link: '/chapter-1/01-filename' },
36+
]
37+
}
38+
],
39+
'/appendix/': [
40+
{
41+
text: '附录',
42+
items: [
43+
{ text: '术语表', link: '/appendix/glossary' },
44+
]
45+
}
46+
],
47+
},
48+
49+
socialLinks: [
50+
{ icon: 'github', link: 'https://github.com/USER/REPO' }
51+
],
52+
53+
footer: {
54+
message: 'FOOTER_MESSAGE',
55+
copyright: 'FOOTER_COPYRIGHT'
56+
},
57+
58+
search: {
59+
provider: 'local',
60+
options: {
61+
translations: {
62+
button: { buttonText: '搜索文档' },
63+
modal: {
64+
noResultsText: '无结果',
65+
footer: { closeText: '关闭' }
66+
}
67+
}
68+
}
69+
},
70+
71+
docFooter: {
72+
prev: '上一章',
73+
next: '下一章'
74+
},
75+
76+
outline: {
77+
label: '本页目录',
78+
level: [2, 3]
79+
},
80+
81+
editLink: {
82+
pattern: 'https://github.com/USER/REPO/edit/master/docs/:path',
83+
text: '在 GitHub 上编辑此页'
84+
},
85+
86+
lastUpdated: {
87+
text: '最后更新',
88+
formatOptions: { dateStyle: 'short' }
89+
}
90+
},
91+
92+
markdown: {
93+
lineNumbers: true,
94+
}
95+
}))

‎.codebuddy/skills/vitepress-docs-deploy/assets/deploy-docs.yml.template‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Deploy Docs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [master]
6+
paths:
7+
- 'docs/**'
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
15+
concurrency:
16+
group: pages
17+
cancel-in-progress: false
18+
19+
jobs:
20+
build:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
26+
- name: Setup Node
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: 22
30+
31+
- name: Setup Pages
32+
uses: actions/configure-pages@v5
33+
with:
34+
enablement: true
35+
36+
- name: Install dependencies
37+
run: npm ci
38+
working-directory: docs
39+
40+
- name: Build with VitePress
41+
run: npm run build
42+
working-directory: docs
43+
44+
- name: Upload artifact
45+
uses: actions/upload-pages-artifact@v3
46+
with:
47+
path: docs/.vitepress/dist
48+
49+
deploy:
50+
environment:
51+
name: github-pages
52+
url: ${{ steps.deployment.outputs.page_url }}
53+
runs-on: ubuntu-latest
54+
needs: build
55+
steps:
56+
- name: Deploy to GitHub Pages
57+
id: deployment
58+
uses: actions/deploy-pages@v4

‎.codebuddy/skills/vitepress-docs-deploy/assets/index.md.template‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
layout: home
3+
4+
hero:
5+
name: "PROJECT_TITLE"
6+
text: "PROJECT_SUBTITLE"
7+
tagline: TAGLINE_TEXT
8+
actions:
9+
- theme: brand
10+
text: 开始学习
11+
link: /chapter-1/01-intro
12+
- theme: alt
13+
text: 查看源码
14+
link: https://github.com/USER/REPO
15+
16+
features:
17+
- icon: 🧠
18+
title: FEATURE_1_TITLE
19+
details: FEATURE_1_DESCRIPTION
20+
link: /chapter-1/01-intro
21+
- icon: 💾
22+
title: FEATURE_2_TITLE
23+
details: FEATURE_2_DESCRIPTION
24+
link: /chapter-2/01-intro
25+
- icon: 🔍
26+
title: FEATURE_3_TITLE
27+
details: FEATURE_3_DESCRIPTION
28+
link: /chapter-3/01-intro
29+
30+
---
31+
32+
## 教程概览
33+
34+
BRIEF_INTRO_TEXT
35+
36+
### Part 1 · PART1_NAME
37+
38+
PART1_DESCRIPTION
39+
40+
[开始学习 →](/chapter-1/01-intro)
41+
42+
### Part 2 · PART2_NAME
43+
44+
PART2_DESCRIPTION
45+
46+
[开始学习 →](/chapter-2/01-intro)
47+
48+
### Part 3 · PART3_NAME
49+
50+
PART3_DESCRIPTION
51+
52+
[开始学习 →](/chapter-3/01-intro)
53+
54+
---
55+
56+
## 技术栈
57+
58+
| 层级 | 技术 | 用途 |
59+
|------|------|------|
60+
| **TECH_1_CAT** | TECH_1_NAME | TECH_1_USE |
61+
62+
---
63+
64+
## 学习路径
65+
66+
| 路径 | 时长 | 适合人群 |
67+
|------|------|----------|
68+
| **PATH_1_NAME** | PATH_1_DURATION | PATH_1_AUDIENCE |

‎.codebuddy/skills/vitepress-docs-deploy/assets/package.json.template‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"name": "PROJECT-docs",
3+
"version": "1.0.0",
4+
"private": true,
5+
"scripts": {
6+
"dev": "vitepress dev",
7+
"build": "vitepress build",
8+
"preview": "vitepress preview"
9+
},
10+
"devDependencies": {
11+
"vitepress": "^1.6.0",
12+
"mermaid": "^11.0.0",
13+
"vitepress-plugin-mermaid": "^2.0.0"
14+
}
15+
}

0 commit comments

Comments
 (0)