文档风格指南
一句话宣言
读者带着问题来，我们直接给答案：先结论、后步骤、再排错；像朋友手把手教，不像说明书念参数。
写任何页面之前，先读上面的宣言，再对照下面的规则。语法层写法（代码组、图标、Linkcard、禁止表格）见文档编写特性。
三条铁律
- 先给结论 — 页面开头用一两句话说清「这页解决什么问题、适合谁」。禁止用「本文将介绍……」开场。
- 每步可照做 — 步骤里的每个值都具体：端口、路径、默认值、按钮名、Token 名。禁止「自行设置」「根据需要配置」这类空泛指令。
- 排错来收尾 — 每页末尾放「验证与排错」：一个可执行的验证动作 + 2~5 个常见失败场景及对应解法。
先判断页面类型
动笔前识别这页属于哪种类型，套用对应骨架：
教程（第一次做这件事）— 目标 → 前置条件 → 编号步骤 → 验证 指南（做一件具体的事）— 直接结论 → 步骤或选项 → 排错 参考（查参数）— 定义列表逐字段说明：名称 — 默认值，作用 概念（理解原理）— 类比 → 图示 → 术语表
语气
- 称呼读者用「你」，不用「用户」
- 命令直接给：「安装 NapCat」「编辑
config/bot_config.toml」，不说「请考虑」 - 警告放在正文需要的位置，不堆在页面开头
- 正向引导：先说「这样做能获得什么」，风险随后
- 一句话能说清的不用两句
配置展示：代码块 + 注释
配置类内容（插件设置、配置文件、环境变量）优先用完整配置模板 + 行尾注释，不用逐条定义列表：
- 完整可复制 — 给出整段配置（含所有节、所有字段），读者复制即得，改注释标注处即可用
- 注释讲三件事 — 字段作用、默认值、注意事项（如「必须大于 0」「与 NapCat 设置一致」）
- 省略字段 = 用默认值 — 模板中写全字段让默认值可见，读者能直观看到哪些可调
- 定义列表仍可用于单个重点字段的展开讲解（如易错字段），但整段配置一律用代码块
- 遵循 markdown-features 的 code-group 写法，标签带
~vscode-icons:file-type-toml~
侧边栏规则
侧边栏与页面同样遵循风格宣言：读者要能扫一眼就找到对的那条。
- 分组 — 同级条目 ≥5 个且能按读者心智归类时，必须分组。分组名说清区分维度，如 QQ 按接入路线分「本地客户端登录」「开放平台机器人」；不要用「其他」「杂项」这类兜底名
- 条目命名 —
名称 — 差异化描述：描述讲「是什么、适合谁、特色」，不讲「XX 的文档」。名字本身能区分时（如「数据库」「Bot 配置」）不必加描述 - 概览条目 — 每节第一项放概览页，命名「X 概览」（en: X Overview）
- 镜像对称 — zh/en 分组、条目、顺序一一对应，zh 为权威；新增页面必须同时进两侧边栏
- 正向措辞 — 与页面语气一致：写「官方推荐」不写「可用（测试中）」
风格锚点（可联网检索）
拿不准时，检索以下知名来源对齐：
- 结构：Diátaxis（diataxis.fr）— 教程/指南/参考/概念四类划分
- 语气：Stripe 文档（stripe.com/docs）与 Google 开发者文档风格指南（developers.google.com/style）的 Voice & Tone 章节