撰写新文档

适用对象

• 负责维护某子系统或运维文档的技术部成员

流程概览

步骤

1. 判断文档类型

先回答：这篇文档是解释概念、带人入门、解决某个任务，还是提供参数查表？对照 文档结构 选择目录。

2. 创建文件

在 docs/ 或 docs/systems/<系统名>/ 下新建 .md 文件。文件名使用 Pascal-Case 或 kebab-case，与同级现有文件保持一致。

3. 编写内容

组织级 / 运维类 建议包含：

• 适用对象
• 目的
• 操作步骤
• 常见错误
• 风险提示

系统级技术文档 按 Diátaxis 类型写作，Reference 类文档优先用表格与代码块，减少叙述性段落。

Mermaid 图表：节点内换行使用 <br/>，不要用 \n。标签含 @、/ 等特殊字符时用引号包裹，如 Node["@docusaurus/theme-mermaid"]。示例：

4. 注册侧边栏

在 sidebars.ts 对应分类的 items 中加入 doc ID。未注册的文档仍可通过 URL 访问，但不会出现在导航中。

5. 本地验证

npm run build

构建成功且无 broken link 警告（项目当前为 warn 级别）后再提交。

新增整个子系统文档

1. 在 docs/systems/ 下创建 <系统名>/ 目录及 index.md
2. 按标准目录结构补充各分类页面
3. 在 sidebars.ts 的「项目文档」下新增 category，参考 cssagpt / cssalottery 的配置
4. 可选：在 docusaurus.config.ts footer「相关链接」中加入线上地址

常见错误

• ❌ 把 How-to 写成大段原理说明（应放到 Overview）
• ❌ 新建文件但忘记更新 sidebars.ts，导致导航找不到
• ❌ Mermaid 节点用 \n 换行，页面上显示为字面字符
• ❌ 未执行 npm run build 就合并，引入 Markdown 语法或链接错误

参考

• 项目内 doc-writing Skill：.cursor/skills/doc-writing/SKILL.md
• 示例系统：cssagpt、cssalottery 文档完整度较高，可直接参照