OpenTBook
创作规范
OpenTBook 文档创作规范，涵盖目录命名、文件组织、Markdown 格式与中文命名支持
概述
本文档定义 OpenTBook 知识库的创作规范，帮助团队成员快速上手并保持内容一致性。
目录与文件命名
命名格式
所有 content/ 下的目录和文件统一使用 数字前缀 控制排序：
{数字}.{名称}/ # 目录
{数字}.{名称}.md # 文件
数字前缀仅影响导航排序，不会出现在最终 URL 中。
支持中文命名
OpenTBook 同时支持英文命名和中文命名两种风格：
| 风格 | 示例 | URL 效果 | 适用场景 |
|---|---|---|---|
| 英文短横线 | 1.quick-start.md | /projects/quick-start | 需要简洁 URL、对外分享 |
| 中文命名 | 1.快速开始.md | /projects/快速开始 | 内部知识库、快速识别内容 |
中文命名在浏览器地址栏中正常显示，但复制链接时会被编码为
%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B 等形式。如果文档主要面向团队内部使用，中文命名完全可行。推荐策略
- 顶层分区目录（
1.projects/、2.team/等）：保持英文，因为它们构成 URL 的主路径 - 项目子目录和文档文件：可自由选择英文或中文
- 同一目录内保持风格一致：不要混用英文和中文命名
命名示例
content/
1.projects/ # 顶层保持英文
OpenTBook/
1.prd.md # 英文命名
2.writing-guide.md # 英文命名
数据平台/ # 中文项目目录 ✅
1.项目概览.md # 中文文件名 ✅
2.架构设计.md # 中文文件名 ✅
2.team/
会议纪要/ # 中文子目录 ✅
2026-04-13-周会.md # 日期+中文 ✅
3.skills/
张三/
1.技能概览.md # 中文文件名 ✅
papers/ # 英文也可以
Frontmatter 规范
每个 .md 文件 必须 以 YAML frontmatter 开头：
---
title: 页面标题 # 必填，中文
description: 页面描述，50-160 字符 # 必填，用于搜索和 SEO
authors: # 必填，至少一位作者
- name: 作者姓名
date: 2026-04-13 # ISO 日期格式
model: claude-opus-4-6 # AI 辅助模型，纯人工写 human
---
可选字段
navigation:
title: 侧边栏短标题 # 省略则使用 title
icon: i-lucide-book-open # Lucide 图标名
toc: false # 关闭右侧目录（默认 true）
draft: true # 草稿状态，不出现在导航中
model 字段说明
| 值 | 含义 |
|---|---|
human | 纯人工撰写 |
claude-opus-4-6 | Claude Opus 4.6 辅助 |
claude-sonnet-4-6 | Claude Sonnet 4.6 辅助 |
gpt-4o | GPT-4o 辅助 |
Markdown 格式
标题规则
- 使用 ATX 风格（
#开头） - 正文从 H2 开始，H1 由 Docus 从 frontmatter
title自动生成 - 标题层级不跳级：H2 之后只能是 H3，不能直接跳到 H4
## 这是 H2 ✅
### 这是 H3 ✅
##### 跳到 H5 ❌（跳级了）
中英文混排
中文与英文、数字之间 加一个空格：
使用 Git 管理代码 ✅
使用Git管理代码 ❌
共 3 个文件 ✅
共3个文件 ❌
代码块
必须指定语言标识：
```python
def hello():
print("Hello")
```
列表
无序列表使用 -（不用 *）：
- 第一项
- 第二项
- 子项
提示框
使用 MDC 语法，不要用 > blockquote：
::note
这是一条信息提示。
::
::tip
这是一条建议。
::
::warning
这是一条警告。
::
::caution
这是一条危险提示。
::
代码组
多语言示例使用 ::code-group：
::code-group
```bash [pnpm]
pnpm install
```
```bash [npm]
npm install
```
::
图片规范
- 图片存放在
public/images/{section}/目录下 - Markdown 中使用绝对路径引用：
/images/{section}/{filename}.png - 建议使用 PNG（截图）或 SVG（图表）格式
- 文件名使用英文短横线命名：
architecture-overview.png
Git 提交规范
Commit 格式
type(scope): subject
| type | 用途 | 示例 |
|---|---|---|
docs | 文档内容变更 | docs(guide): 添加快速开始指南 |
feat | 新模板/新功能 | feat(template): 添加实验记录模板 |
fix | 修正错误内容 | fix(research): 修正算法公式错误 |
style | 格式调整 | style: 统一标题层级格式 |
refactor | 重构文档结构 | refactor: 重新组织工程文档分类 |
chore | 工具链变更 | chore: 更新 markdownlint 规则 |
分支命名
| 分支 | 用途 | 示例 |
|---|---|---|
docs/{topic} | 文档编写 | docs/quick-start |
chore/{task} | 配置变更 | chore/update-lint-rules |
快速检查清单
开始写作前，确认以下几点：
- 文件有完整的 frontmatter（title、description、authors）
- 正文从 H2 开始，无 H1
- 标题层级无跳级
- 中英文之间有空格
- 代码块有语言标识
- 图片路径使用
/images/...绝对路径