文档站
docs/user-guide/ 和 docs/dev-guide/ 是两个独立的 mdBook 项目。每本书的 src/ 目录保存简体中文源文件,en/ 目录保存英文源文件,共用同一份 book.toml 配置;两本书的站点主题与语言切换器统一保存在 docs/theme/。
编辑章节
中英文源文件独立维护,内容变化应在同一提交中同步完成:
- 新增、移动或删除章节时,请同时修改
src/SUMMARY.md和en/SUMMARY.md,保持两种语言的页面文件路径完全一致。 - 代码块中的命令、路径、配置键和标识符保持一致,正文与注释可以按语言翻译。
- 同一本书内部使用相对
.md链接;跨书(用户手册与开发指南之间)使用站点绝对 URL(https://cjv.zxilly.com/book/...),因为两本书分别构建。 - 移动或重命名已发布页面时,请在
book.toml的[output.seo.html.redirect]中保留旧地址重定向。
docs/theme/cjv-i18n.js 和 cjv-i18n.css 提供顶栏语言切换器。它通过替换当前 URL 中的 /zh-CN/ 与 /en/ 路径段来切换语言,因此两种语言必须具有相同的页面路径。由于中英文标题生成的 HTML 锚点 ID 不同,切换语言会打开对应章节顶部,并去掉原语言的 #anchor 标题锚点。
本地预览
完整站点构建与检查(推荐)
安装 mdBook 0.5.3、mdbook-sitemap 0.1.1、mdbook-seo 和 Python 3.9 以上版本,在仓库根目录执行:
cargo install mdbook-sitemap --version 0.1.1 --locked
cargo install --git https://github.com/Zxilly/mdbook-seo --rev de97785a384305e149dc52ac24f9f1d8f827bb9c --locked
python3 scripts/build-docs.py
python3 -m http.server --directory web/dist/client 8000
在浏览器中访问 http://localhost:8000/book/user-guide/zh-CN/(或 /en/),即可预览与线上发布完全一致的主题和语言切换器。在 Windows 上如果未配置 python3,可将其换为 python。
scripts/build-docs.py 会为四份书(用户手册与开发指南的中英文版)设置源语言、标题和站点路径,在临时目录中加入共享主题,并自动检查所有生成的 HTML 页面中的内部链接、跨书 /book/ 链接、静态资源和 #anchor 锚点。传入 --output <dir> 可指定其他输出目录,--check-only 只检查已有产物而不重新调用 mdbook。Markdown 格式检查命令见测试与检查。
每本书通过 [output.seo] 使用 mdbook-seo 渲染 HTML,同时生成 canonical、description、hreflang、Open Graph 和 Twitter 元数据。HTML 渲染选项位于 [output.seo.html]。共享的 docs/theme/head.hbs 提供统计代码,docs/user-guide/seo-pages.json 保存安装页的中英文元数据覆盖;构建时分别设置语言的规范域名路径和 locale。
mdbook-sitemap 通过 [output.sitemap] 发现章节,完整构建将 seo/ 产物复制到原有公开路径。scripts/site_map.py 读取生成页面中的 canonical,排除 noindex 页面,并合并四份文档与实际已构建的首页、Blog 页面,不再修改 HTML。发布地址不包含后端目录名。继续关闭 include-lastmod,避免将构建日期写成页面修改日期。
编辑时重新构建
修改 Markdown 或 SEO 配置后,重新执行 python3 scripts/build-docs.py 并刷新静态预览。这是完整中英文站点的预览入口,与生产使用相同的临时构建目录、主题和元数据。直接运行 mdbook serve 不在 SEO 后端当前验证的兼容范围内。
Pages 部署
.github/workflows/pages.yml 在相关前端、文档或部署文件推送到 master、手动运行或被发布流程调用时部署。它先构建 web/ 前端,再向 web/dist/client/ 中放入安装器和四份手册输出:
web/dist/client/
dl/{official,mirror}/{os}_{arch}/cjv-init[.exe]
book/user-guide/{zh-CN,en}/
book/dev-guide/{zh-CN,en}/
请保持这一构建顺序:在 web/ 中执行 pnpm build 会清空 web/dist/client/。PR 检查和发布工作流使用完全相同的 mdBook 版本与构建入口:
python3 scripts/build-docs.py
整个 web/dist/client 作为一个 github-pages artifact 部署到 GitHub Pages 与腾讯云 EdgeOne。安装器来源与发布顺序见发布流程。