Skip to content

Commit cdd2057

Browse files
committed
� Add doc development guide
1 parent 067bb81 commit cdd2057

File tree

3 files changed

+141
-0
lines changed

3 files changed

+141
-0
lines changed

doc/docs/.vitepress/config.mts

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,12 @@ export default defineConfig({
8484
{ text: 'Prompt Development', link: '/en/backend/prompt-development' }
8585
]
8686
},
87+
{
88+
text: 'Documentation Development',
89+
items: [
90+
{ text: 'Docs Development Guide', link: '/en/docs-development' }
91+
]
92+
},
8793
{
8894
text: 'Container Build & Containerized Development',
8995
items: [
@@ -196,6 +202,12 @@ export default defineConfig({
196202
{ text: '提示词开发', link: '/zh/backend/prompt-development' }
197203
]
198204
},
205+
{
206+
text: '文档开发',
207+
items: [
208+
{ text: '文档开发指南', link: '/zh/docs-development' }
209+
]
210+
},
199211
{
200212
text: '容器构建与容器化开发',
201213
items: [

doc/docs/en/docs-development.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Documentation Development Guide
2+
3+
## 📘 Introduction
4+
We use VitePress to develop and manage our documentation. This guide explains how to add, edit, preview, and build docs in this project with a consistent structure for both Chinese and English.
5+
6+
## 🗂️ Project Structure
7+
```text
8+
/doc
9+
├─ package.json
10+
└─ docs
11+
├─ .vitepress
12+
│ └─ config.mts # Site & sidebar configuration
13+
├─ cn # Chinese docs
14+
├─ en # English docs
15+
├─ assets # Site assets
16+
├─ public # Static public assets
17+
└─ index.md
18+
```
19+
20+
## 📦 Install Dependencies
21+
From the `doc` directory:
22+
23+
```bash
24+
pnpm install
25+
```
26+
27+
## 💻 Local Development
28+
Start the dev server:
29+
30+
```bash
31+
pnpm vitepress dev docs
32+
```
33+
34+
After successfully start, visit:
35+
36+
- `http://localhost:5173/doc`
37+
38+
## ✍️ Add or Edit Docs
39+
- Put Chinese docs under `doc/docs/zh` and English docs under `doc/docs/en`.
40+
- Use kebab-case file names, e.g., `getting-started.md`.
41+
- Routes map to file paths, e.g.:
42+
- `doc/docs/zh/foo/bar.md``/zh/foo/bar`
43+
- `doc/docs/en/foo/bar.md``/en/foo/bar`
44+
45+
## 🧭 Sidebar and Navigation
46+
- The sidebar is configured in `doc/docs/.vitepress/config.mts`.
47+
- An entry for this guide has been added right after "Backend Development": `/zh/docs-development` (Chinese) and `/en/docs-development` (English).
48+
- For new pages, add links in the corresponding locale's sidebar and ensure paths match the file locations.
49+
50+
## 🖼️ Assets
51+
- Prefer `doc/docs/public` for shared assets and reference them using absolute paths, e.g., `/images/logo.png`.
52+
- Page-specific assets can live alongside the page and be referenced via relative paths.
53+
54+
## ✅ Build and Validate
55+
Before committing, build the docs to check for dead links and other issues:
56+
57+
```bash
58+
pnpm run docs:build
59+
```
60+
61+
Preview the production build locally:
62+
63+
```bash
64+
pnpm run docs:preview
65+
```

doc/docs/zh/docs-development.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# 文档开发指南
2+
3+
## 📘 简介
4+
我们使用 VitePress 进行文档的开发与管理,统一组织中英文内容、侧边栏与导航配置,支持本地开发预览与构建发布。本文档指导你如何在本项目中新增、编辑与校验文档。
5+
6+
## 🗂️ 目录结构
7+
```text
8+
/doc
9+
├─ package.json
10+
└─ docs
11+
├─ .vitepress
12+
│ └─ config.mts # 站点与侧边栏配置
13+
├─ zh # 中文文档目录
14+
├─ en # 英文文档目录
15+
├─ assets # 站点资源
16+
├─ public # 公共静态资源
17+
└─ index.md
18+
```
19+
20+
## 📦 安装依赖
21+
`doc` 目录下执行:
22+
23+
```bash
24+
pnpm install
25+
```
26+
27+
## 💻 本地开发
28+
启动本地开发服务器:
29+
30+
```bash
31+
pnpm vitepress dev docs
32+
```
33+
34+
启动成功后,请通过以下地址访问:
35+
36+
- `http://localhost:5173/doc`
37+
38+
## ✍️ 新增与编辑文档
39+
- 中文文档放在 `doc/docs/zh`,英文文档放在 `doc/docs/en`
40+
- 文件命名建议使用小写短横线(kebab-case),例如:`getting-started.md`
41+
- 页面路径与文件路径一一对应,例如:
42+
- `doc/docs/zh/foo/bar.md` 将通过 `/zh/foo/bar` 访问;
43+
- `doc/docs/en/foo/bar.md` 将通过 `/en/foo/bar` 访问。
44+
45+
## 🧭 配置侧边栏与导航
46+
- 侧边栏配置位于 `doc/docs/.vitepress/config.mts`
47+
- 若新增页面,请在对应语言的 `sidebar` 中添加链接项,注意与文件路径一致。
48+
49+
## 🖼️ 使用资源
50+
- 推荐将公共图片放到 `doc/docs/public`,通过绝对路径引用,例如:`/images/logo.png`
51+
- 也可以将与页面紧密相关的资源放入同级目录,并使用相对路径引用。
52+
53+
## ✅ 构建与校验
54+
在正式提交前请进行构建,以检查死链(dead links)等问题:
55+
56+
```bash
57+
pnpm run docs:build
58+
```
59+
60+
构建成功后可本地预览:
61+
62+
```bash
63+
pnpm run docs:preview
64+
```

0 commit comments

Comments
 (0)