Skip to content

Commit 78a6d61

Browse files
devcxldevcxl
committed
feat: Jekyll → VitePress 文档站迁移
- 安装 vitepress，添加 docs:dev/docs:build/docs:preview scripts - 创建 docs/.vitepress/config.ts（自动侧边栏、导航栏、搜索、社交链接） - 首页改为 VitePress home layout + npm badge + 命令一览 - 修复内部链接格式为 clean URL - 更新 pages.yml 为 VitePress 构建流程 - 删除 Jekyll 配置 docs/_config.yml - 更新 .gitignore 添加 .vitepress-dist
1 parent b5726d3 commit 78a6d61

20 files changed

Lines changed: 3105 additions & 273 deletions

‎.github/workflows/pages.yml‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
name: Deploy docs to GitHub Pages
1+
name: Deploy VitePress to GitHub Pages
22

33
on:
44
push:
55
branches: [main]
66
paths:
77
- "docs/**"
8-
- "README.md"
9-
- "_config.yml"
8+
- "package.json"
9+
- ".github/workflows/pages.yml"
1010
workflow_dispatch:
1111

1212
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
@@ -26,17 +26,22 @@ jobs:
2626
steps:
2727
- uses: actions/checkout@v4
2828

29-
- name: Setup Pages
30-
uses: actions/configure-pages@v5
31-
32-
- name: Build with Jekyll
33-
uses: actions/jekyll-build-pages@v1
29+
- name: Setup Node.js
30+
uses: actions/setup-node@v4
3431
with:
35-
source: ./docs
36-
destination: ./_site
32+
node-version: 20
33+
cache: npm
34+
35+
- name: Install dependencies
36+
run: npm ci
37+
38+
- name: Build VitePress
39+
run: npm run docs:build
3740

3841
- name: Upload artifact
3942
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: .vitepress-dist
4045

4146
deploy:
4247
environment:

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
node_modules/
22
dist/
33
.worktree/
4+
.vitepress-dist/

‎docs/.vitepress/config.ts‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
import { defineConfig } from 'vitepress'
2+
import { readdirSync, statSync } from 'node:fs'
3+
import { join } from 'node:path'
4+
import type { DefaultTheme } from 'vitepress'
5+
6+
function getSidebar(): DefaultTheme.Sidebar {
7+
const docsDir = join(import.meta.dirname, '..')
8+
const sidebar: DefaultTheme.Sidebar = {}
9+
10+
const dirLabels: Record<string, string> = {
11+
guides: '使用指南',
12+
adr: '架构决策记录',
13+
dev: '开发文档',
14+
prd: '产品需求文档',
15+
}
16+
17+
for (const dir of ['guides', 'adr', 'dev', 'prd']) {
18+
const fullDir = join(docsDir, dir)
19+
const items: DefaultTheme.SidebarItem[] = []
20+
const entries = readdirSync(fullDir).sort()
21+
for (const entry of entries) {
22+
if (entry.startsWith('.')) continue
23+
const fullPath = join(fullDir, entry)
24+
if (entry.endsWith('.md')) {
25+
const name = entry.replace('.md', '')
26+
items.push({
27+
text: name.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
28+
link: `/${dir}/${name}`,
29+
})
30+
} else if (statSync(fullPath).isDirectory()) {
31+
const subEntries = readdirSync(fullPath).sort().filter(e => e.endsWith('.md'))
32+
if (subEntries.length > 0) {
33+
items.push({
34+
text: entry.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
35+
collapsed: dir === 'dev' && entry === 'tasks',
36+
items: subEntries.map(e => ({
37+
text: e.replace('.md', '').replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
38+
link: `/${dir}/${entry}/${e.replace('.md', '')}`,
39+
})),
40+
})
41+
}
42+
}
43+
}
44+
if (items.length > 0) {
45+
sidebar[`/${dir}/`] = [{ text: dirLabels[dir] || dir, items }]
46+
}
47+
}
48+
49+
return sidebar
50+
}
51+
52+
export default defineConfig({
53+
title: 'opencode-cabbage',
54+
description: '全流程开发 OpenCode 插件 — 需求→设计→任务→编码→测试→审查→自动合并',
55+
srcDir: '.',
56+
outDir: '../.vitepress-dist',
57+
lastUpdated: true,
58+
cleanUrls: true,
59+
60+
themeConfig: {
61+
nav: [
62+
{ text: '首页', link: '/' },
63+
{ text: '快速开始', link: '/guides/quickstart' },
64+
{
65+
text: '使用指南',
66+
items: [
67+
{ text: '快速开始', link: '/guides/quickstart' },
68+
{ text: '配置指南', link: '/guides/configuration' },
69+
{ text: '使用指南', link: '/guides/usage' },
70+
{ text: '架构概览', link: '/guides/architecture' },
71+
],
72+
},
73+
{
74+
text: '开发',
75+
items: [
76+
{ text: '贡献指南', link: '/dev/guides/contributing' },
77+
{ text: '技术方案', link: '/dev/specs/opencode-cabbage-docs-and-pages' },
78+
{ text: 'VitePress 迁移', link: '/dev/specs/vitepress-docs-migration' },
79+
{ text: 'Out of Scope', link: '/dev/out-of-scope' },
80+
],
81+
},
82+
{
83+
text: 'ADR',
84+
items: [
85+
{ text: '0001 - 替换 OpenSpec', link: '/adr/0001-replace-openspec-with-full-flow' },
86+
{ text: '0002 - Jekyll 文档站', link: '/adr/2026-07-10-jekyll-github-pages-docs' },
87+
{ text: '0003 - 迁移 VitePress', link: '/adr/2026-07-10-jekyll-to-vitepress' },
88+
],
89+
},
90+
{
91+
text: 'PRD',
92+
items: [
93+
{ text: 'Docs & Pages', link: '/prd/opencode-cabbage-docs-and-pages' },
94+
{ text: 'VitePress 迁移', link: '/prd/vitepress-docs-migration' },
95+
],
96+
},
97+
],
98+
99+
sidebar: getSidebar(),
100+
101+
search: {
102+
provider: 'local',
103+
options: {
104+
translations: {
105+
button: {
106+
buttonText: '搜索',
107+
buttonAriaLabel: '搜索文档',
108+
},
109+
modal: {
110+
displayDetails: '显示详情',
111+
noResultsText: '未找到相关结果',
112+
resetButtonTitle: '清除搜索',
113+
footer: {
114+
selectText: '选择',
115+
navigateText: '切换',
116+
closeText: '关闭',
117+
},
118+
},
119+
},
120+
},
121+
},
122+
123+
socialLinks: [
124+
{ icon: 'github', link: 'https://github.com/devcxl/opencode-cabbage' },
125+
],
126+
127+
editLink: {
128+
pattern: 'https://github.com/devcxl/opencode-cabbage/edit/main/docs/:path',
129+
},
130+
131+
lastUpdated: {
132+
text: '最后更新',
133+
},
134+
135+
docFooter: {
136+
prev: '上一页',
137+
next: '下一页',
138+
},
139+
},
140+
})

‎docs/_config.yml‎

Lines changed: 0 additions & 18 deletions
This file was deleted.

‎docs/adr/2026-07-10-jekyll-github-pages-docs.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR 0002: 使用 Jekyll + GitHub Pages 部署文档站点
22

3-
**状态:** Accepted
3+
**状态:** Superseded（被 [ADR 0003](/adr/2026-07-10-jekyll-to-vitepress) 替代）
44
**日期:** 2026-07-10
55

66
## 背景

‎docs/adr/2026-07-10-jekyll-to-vitepress.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# ADR 0003: 从 Jekyll 迁移到 VitePress
2+
3+
**状态:** Accepted
4+
**日期:** 2026-07-10
5+
**上级:** [ADR 0002](/adr/2026-07-10-jekyll-github-pages-docs)（被替代）
6+
7+
## 背景
8+
9+
[ADR 0002](/adr/2026-07-10-jekyll-github-pages-docs) 选择了 Jekyll + GitHub Pages 作为文档站方案，理由是"零运维成本、push 即部署"。但在实际使用中暴露了以下问题：
10+
11+
1. **Ruby 生态割裂**：项目是 TypeScript/Vite 技术栈，Jekyll 需要 Ruby 环境和 Bundler，贡献者本地调试需要额外安装 Ruby，增加了入门门槛
12+
2. **构建受限**：Jekyll 的 GitHub Pages 构建基于 GitHub 的托管环境，无法自定义构建流程，Gemfile 依赖受限
13+
3. **搜索缺失**：Jekyll 默认不提供全文搜索，需要集成第三方插件（如 lunr.js），而 GitHub Pages 不运行自定义插件
14+
4. **开发体验差**：Jekyll 的 livereload 需要额外配置，修改配置后需要重启
15+
16+
## 决策
17+
18+
将文档站从 Jekyll 迁移到 **VitePress**，使用 GitHub Actions 构建并部署到 GitHub Pages。
19+
20+
## 选择 VitePress 的原因
21+
22+
| 维度 | VitePress | Jekyll |
23+
|------|-----------|--------|
24+
| 技术栈 | TypeScript + Vite，与项目一致 | Ruby，与项目割裂 |
25+
| 开发体验 | 热更新 < 1s，配置热重载 | 需手动刷新，配置需重启 |
26+
| 搜索 | 内置 minisearch，零配置 | 需第三方插件 |
27+
| 构建速度 | Vite 二次构建极快 | Jekyll 每次全量构建 |
28+
| 维护方 | Vue 团队（Evan You） | 社区 |
29+
| 导航/侧边栏 | 内置自动生成 | 需手动配置或插件 |
30+
| 主题 | 默认主题即开即用 | 受 GitHub Pages 支持列表限制 |
31+
32+
## 备选方案
33+
34+
| 方案 | 未采纳原因 |
35+
|------|-----------|
36+
| 保留 Jekyll | 已暴露上述问题，且文档站有 19 个 `.md` 文件，搜索和导航需求日益迫切 |
37+
| Docusaurus | 功能丰富但偏重，对于 19 个页面的文档站是过度设计；React 技术栈与项目 Vue 倾向不一致 |
38+
| Nextra | 依赖 Next.js，引入额外框架依赖 |
39+
| 纯 HTML | 维护成本高，不符合"文档站"定位 |
40+
41+
## 迁移范围
42+
43+
- **保留**：全部 19 个 `.md` 文件内容不变，目录结构不变
44+
- **新增**：`docs/.vitepress/config.ts`（VitePress 配置）、`.github/workflows/pages.yml`（CI 构建部署）
45+
- **删除**：`docs/_config.yml`（Jekyll 配置）
46+
- **改造**：`docs/index.md`（从 Jekyll 首页改为 VitePress 首页布局）
47+
- **不修改**：文档内容、目录结构、文件名
48+
49+
## 后果
50+
51+
### 正向
52+
53+
- 技术栈统一：贡献者无需安装 Ruby，仅需 Node.js >= 18
54+
- 开发体验提升：`npm run docs:dev` 即可启动热更新开发服务器
55+
- 全文搜索：内置 minisearch，用户在文档站内即可搜索全部内容
56+
- 自动侧边栏：按目录结构自动生成，新增文档无需手动注册
57+
- 构建可控：GitHub Actions 上自定义构建流程，不受 GitHub Pages 托管限制
58+
- 未来扩展：VitePress 支持自定义主题、Vue 组件嵌入，为后续扩展留空间
59+
60+
### 风险
61+
62+
- 需要创建 GitHub Actions workflow（`.github/workflows/pages.yml`），而非 Jekyll 的自动构建
63+
- 需要在仓库 Settings → Pages 中将 Build source 从 "Deploy from a branch" 改为 "GitHub Actions"
64+
- 旧版 Jekyll 链接（如有外部引用）需要重定向（影响极小，文档站尚未广泛传播）
65+
66+
## 技术方案
67+
68+
详见 [VitePress 文档站迁移技术方案](/dev/specs/vitepress-docs-migration)。

‎docs/dev/out-of-scope.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,12 @@
88
- 多语言/国际化文档 — 非必要
99
- 文档搜索功能 — 可通过 GitHub Pages 搜索替代
1010
- 版本化文档（多版本切换） — 待项目成熟后再考虑
11+
12+
## VitePress 文档站迁移
13+
14+
以下需求在访谈中明确排除，记录于此供后续参考：
15+
16+
- 自定义 VitePress 主题 — 使用默认主题
17+
- 自定义域名配置
18+
- 多语言支持
19+
- 文档内容重写/重组 — 仅迁移，不修改内容

0 commit comments

Comments
 (0)