能力地图与验证边界

模板的关键不是功能数量，而是每项功能都有明确输入、输出和失败边界。

链路阶段	输入	输出	发布前阻断项
内容发现	projects 中的文档和资源	经验证的 DocumentCatalog	越界路径、缺失本地图片、项目规则冲突
HTML 构建	内容清单和 Sphinx 配置	中文、英文独立站点	语言首页或导航生成失败
PDF 构建	同一内容清单与 LaTeX 配置	一份或两份可下载 PDF	XeLaTeX、字体、PDF 有效性校验失败
多版本构建	versions.json 与 Git 分支	隔离版本目录	分支或版本定义无效
GitHub 发布	通过验证的构建产物	Artifact 与 GitHub Pages	PR 校验未通过时不部署

输出体验

Web 端提供全文搜索、深色模式、语言切换、版本菜单、编辑入口、PDF 下载和可选的 giscus 讨论。PDF 端保留封面、目录、页眉页码、书签、章节分页、代码块、表格、图片和 WebP 转换策略。

使用模板时的判断原则

如果某项约束只在部署后才会暴露，它就应该被前移到本地检查或 CI。模板中的严格校验不是额外负担，而是为了让文档在用户看到之前就具备可交付性。

下一步可在 内容组织 选择你的仓库模型。