内容约定：让文档可以长期维护

文件命名

内容类型	中文	英文
网站或章节首页	README_zh.md	README.md
正文 Markdown	topic_zh.md	topic.md
正文 reStructuredText	topic_zh.rst	topic.rst
图片和附件	figures/ 或 assets/	同目录共享

同一篇双语内容必须放在同一目录并使用同一基础名，例如 install_zh.md 对应 install.md。目录和文件名使用稳定、可读的英文 snake_case；展示给读者的中文标题写在文档一级标题和 config.yaml 的分类名称中。

每篇技术页面的最小结构

1. 先说明目标和适用版本。

2. 列出不可省略的前置条件。

3. 给出可以直接运行的步骤，并标明运行环境。

4. 提供成功判据，例如日志、文件、界面状态或命令输出。

5. 写出常见失败的下一跳链接。

图片必须跟随文章存放并使用相对路径。构建器会校验本地图片是否真实存在且位于 projects 范围内，因此不要使用看似可用的 …/ 相对逃逸路径。

专业文档的表达原则

命令不是结论。每段命令都应说明执行位置、意图、预期变化和回滚或排查入口。读者需要的是可验证的行动，不是一串无法判断成功与否的指令。