写文档时常常要同时决定读者从哪开始、如何完成首个任务、细节放哪、失败怎么恢复。一个空文档仓库会让每个贡献者重新发明导航、页面职责和发布检查。这套模板用五个聚焦页面、一个本地校验器和严格构建路径，在写产品内容之前先把结构定下来。
模板包含 Markdown 源码、MkDocs 配置、校验脚本和 GitHub Actions 部署工作流。五个页面各司其职：index 引导读者选首个任务，getting-started 完成首次配置，guides 执行单个有界操作，reference 查稳定细节，troubleshooting 从已知故障恢复。目录做不到这些——它只能标注页面名称，无法建立前置条件、测试命令、预期结果和恢复路径。
从最小可验证动作开始写 getting-started。对 API 是带认证请求返回已知响应，对 CLI 是安装后跑一条安全命令，对内部服务是本地开发环境能访问健康检查端点。明确前置条件、给出确切操作、展示预期状态、链接下一个任务。稳定名称、类型、默认值和约束放进 reference，不要全堆进入门页。
给每个页面指定负责人和更新触发条件。API schema 变更触发 reference 审查，引导路径调整触发 getting-started 审查，重复出现的支持问题应新建或更新 troubleshooting。页面归属某个读者决策时才值得存在，否则会让其他页面更难扫描、更新或验证。
校验器检查导航目标存在、每个 Markdown 页面只有一个 H1、本地链接可解析。运行python scripts/validate_docs.py和mkdocs build --strict。校验范围刻意收窄，无法证明 API 端点可用、权限正确或截图匹配当前界面，这些仍需产品级检查。
部署工作流安装固定版本依赖、运行校验器、严格构建站点目录、上传为 Pages 产物并部署。启用 GitHub Actions 作为发布源，工作流跑完后验证公开 URL，别把绿色构建当作已发布。不要把生产凭据、私有示例或客户数据放进仓库，Pages 内容即使仓库私有也是公开的。
这套模板解决的是空仓库时每个贡献者都要重新发明导航和发布检查的问题。先跑通一条测试路径，再按读者需求逐步加页面——需要稳定细节时加 reference，出现可识别症状和恢复路径时加 troubleshooting，需要理解设计选择才能安全使用时加 explanation。模板保持比产品小，但能随产品一起成长。
@DevToolboxHub