#文档编写规范

本规范适用于 docs/ 下的 Markdown 和 MDX 文档。新增或修改文档时，请按以下约定维护内容和元信息。

#文件位置与格式

• 中文文档放在 docs/zh/ 下与内容主题对应的目录中。
• 一般页面使用 .md；需要 React 组件或 MDX 能力时使用 .mdx。
• 编辑 docs/ 中的源文件。doc_build/ 是构建产物，不要手动修改。
• 新增页面时，按需更新所在目录的 _meta.json，以便页面显示在侧边栏中。

#Frontmatter

每篇文档都必须包含 title、description 和 author。例如：

---
title: 页面标题
description: 页面说明
author: 内容作者名称
---

有多位作者时，使用 YAML 列表：

author:
  - 作者一
  - 作者二

author 只写一个或多个作者名称，不写 URL 或 Markdown 链接。作者名称会显示在文章标题下方。

#作者署名

• 新建原创文档时，将实际撰写者的名称写入 author。
• 新文档主要转载、翻译或改编自其他作者的资料时，在 author 中注明原作者名称。如果同时加入了实质性的原创内容，也将实际撰写者列入 author。
• 引用外部资料时，在正文中标明可访问的来源链接；来源作者名称仍写在 author 中，不要把链接放进该字段。
• 在已有文档上继续补充内容时，保留 frontmatter 中已有的全部作者名称和顺序，并将本次内容贡献者追加到列表末尾。不要覆盖或删除历史作者。
• Git 提交者不一定是内容作者；只有实际撰写或实质性补充了内容时，才将其列为作者。
• 一篇文章由多篇完整文章整合而成时，在 author 中列出各原文作者；在文章末尾另起一段，说明各部分内容分别来自哪些作者或原文。
• 从外部文档转载内容时，完整保留原文已有的作者署名和来源信息，包括原文标题、发布来源及可用的链接或日期。将原作者列入 author，不要用编者或转载者替换原作者。
• 编者可以添加客观背景注释，例如说明某段是原作者的个人观点，不代表已核实事实或官方规定。注释应明确标为“编者注”，与原文分开，不能让读者误认为注释出自原作者。

#内容组织

• 每页使用一个与 title 相符的一级标题，并按层级组织后续标题。
• 选择清楚、准确的表达；步骤使用有序列表，平行项目使用无序列表，适合比较的信息使用表格。
• 代码块注明语言类型，便于阅读和语法高亮。
• 使用有意义的链接文字，并确认页面链接、外部来源和图片可以访问。
• 涉及游戏机制、军团规定、历史或成员信息时，核对可靠来源；LLM 生成的事实也需要人工确认。

#提交前检查

本地编辑时可以在项目根目录执行：

git diff --check
pnpm run format
pnpm run lint
pnpm run build

pnpm run lint 和 pnpm run build 会检查文档 frontmatter 中的作者字段；构建还会验证 Rspress 页面和导航配置。