项目概览
本模板服务于需要持续维护、需要发布、也需要被读者信任的技术文档。它并不把 Markdown 当作一次性网页原料，而是把内容目录、导航、语言、PDF 与发布环境看成同一个工程系统。
核心设计
设计目标 |
当前机制 |
直接收益 |
|---|---|---|
内容和工具解耦 |
projects 保存内容，source 保存构建系统 |
作者不会误编辑生成副本 |
两种内容模型 |
recursive_tree 与 project_catalog |
同时覆盖手册型和 SDK 集合型仓库 |
多个输出共享事实源 |
DocumentCatalog 供 HTML、PDF、资源同步共同使用 |
降低网页与 PDF 内容不一致的风险 |
本地和 CI 同构 |
相同配置、依赖检查与字体约束 |
预览结果更接近正式发布 |
发布可回溯 |
versions.json 驱动独立 worktree 构建 |
稳定分支不会污染当前开发分支 |
这套模板解决什么问题
普通静态站点往往只解决“把文件转成页面”。当仓库开始包含双语内容、历史版本、复杂图片、PDF 归档和多个维护者时，真正的风险来自导航遗漏、链接越界、不同语言混入搜索结果、PDF 在另一台机器上变形，以及 CI 与本地结果不同。
模板以构建失败替代静默降级：PDF 必须使用 XeLaTeX 和配置中指定的字体；项目目录必须匹配分类规则；本地资源必须被收录；版本配置必须先通过校验。这样的严格性更适合 SDK、硬件平台、机器人系统和工程软件。