> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 文档编写规范

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

## 文件位置与格式

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

## Frontmatter

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

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

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

```yaml
author:
  - 作者一
  - 作者二
```

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

### 作者署名

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

## 内容组织

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

## 提交前检查

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

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

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