文档编写指南
好的文档应该让读者知道：这篇内容适合谁、要解决什么问题，以及如何确认任务已经完成。
推荐结构
每篇操作文档可按以下顺序组织：
- 适用范围：说明读者、场景和必要的前提。
- 准备工作：列出需要事先准备的资料或权限。
- 操作步骤：按真实执行顺序编写，一步只表达一个主要动作。
- 结果确认：说明完成后应该看到什么。
- 常见问题：记录已经验证的处理方法。
描述概念或规则的文档，则可使用「定义 → 说明 → 示例 → 相关内容」的结构。
创建文档
在 docs 目录中新建文件，例如 example-guide.mdx。以下仅为写作模板，请替换成真实、经过核实的信息。
---
title: 文档标题
description: 用一句话说明这篇文档能帮助读者完成什么。
---
# 文档标题
## 适用范围
说明这篇文档适合哪些读者和场景。
## 操作步骤
1. 第一步。
2. 第二步。
## 结果确认
说明预期结果，以及如何判断操作成功。
文件名建议使用小写英文字母和短横线，内容与标题可以使用中文。标题应描述具体任务，避免只写「说明」「其他」等难以辨认的名称。
加入目录
新增文档后，维护人员需要更新 docusaurus.config.ts 中的 docs.include 列表，并在 sidebars.ts 中加入对应文档 ID。
例如，docs/example-guide.mdx 的默认文档 ID 是 example-guide。这样可以明确控制哪些文件会成为公开文档。
常用 Markdown 格式
标题和列表
## 二级标题
### 三级标题
- 无序列表适合并列信息。
- 每条尽量保持简洁。
1. 有序列表适合操作步骤。
2. 按实际执行顺序排列。
链接与图片
内部文档建议使用相对文件链接，构建时可检查链接是否有效。
[快速开始](./quick-start.mdx)
图片示例中的文件需要先放入项目的 static/img 目录。为图片填写有意义的文字说明，方便无法查看图片的读者理解内容。
提示块
提示块适合补充有明确用途的信息：
:::tip[小提示]
补充能帮助读者更顺利完成任务的信息。
:::
写清楚预期结果
不要只写「点击保存」。可以补充「保存后，页面出现成功提示」，让读者能够确认操作结果。
预览与构建
在项目目录中运行：
npm ci
npm run start
准备发布时，先完成类型检查和生产构建：
npm run typecheck
npm run build
生产文件会生成到 build 目录。只有构建成功后，才应发布这些文件；具体服务器发布操作由站点维护人员执行。
发布前检查
- 标题和简介能说明文档的用途。
- 步骤完整，术语前后一致，内容经过核实。
- 链接和图片可以正常访问。
- 文档没有包含账号密码、密钥、服务器连接信息或其他不适合公开的内容。
- 生产构建通过，新增文档已出现在预期的目录中。