双语文档站点的生成器选型
cotty 的站点该用哪个生成器构建?用同一份样例实测了四个。按功能看,Starlight 最合适。最后选了 Hugo:它是单个程序,不依赖 JavaScript 的包生态,缺的部分可以用我们自己的模板和脚本补上。
发现
方法
样例是从 cotty 自己的笔记里取的一组中英文成对的页面:一个产品页、一篇带元数据的 RFC、一篇文章。链接写成指向 .md 文件的相对路径,也就是代码仓库的浏览界面能跟随的写法。每个生成器都构建了这份样例。然后注入错误:缺一篇译文、链接指向不存在的页面、链接指向不存在的锚点、非法的元数据值。
表里的内容都是 2026-11-22 的第一手结果。版本是 Starlight 0.43.1(Astro 7.4)、Docusaurus 3.10.2、VitePress 1.6.4,以及 Hugo 0.170.1 加 Hextra 主题。
结果
| 检查项 | Starlight | Docusaurus | VitePress | Hugo 加 Hextra |
|---|---|---|---|---|
并排目录 en/ 和 zh/ |
支持 | 不支持。译文必须放进它自己的 i18n/… 目录 |
支持 | 支持 |
| 把相对链接改写成站点地址 | 需第三方插件 | 内置 | 内置 | 由主题提供 |
| 拦住坏链接和坏锚点 | 需第三方插件,两种都拦 | 内置,两种都拦 | 只拦坏链接 | 都不拦 |
| 缺一篇译文 | 回退到英文并提示。指向该页的链接会坏 | 相对链接出错,构建中止 | 构建中止 | 未测 |
| 从文本生成图(mermaid) | 第三方插件 | 官方插件 | 第三方插件,2024-09 之后没有更新 | 主题内置 |
| 中文搜索 | 内置,按词切分 | 第三方插件,按词切分 | 内置,但中文不切分 | 主题内置,按单字切分 |
| 带类型的元数据 | 内置。非法值会中止构建 | 无 | 无 | 无 |
| 源文件要迁就的地方 | 无 | 要关掉两个默认行为 | 标题必须写在正文里。内容必须放在项目目录内 | 首页必须叫 _index.md |
| 依赖 | 432 MB,约 500 个包 | 561 MB,约 1200 个包 | 278 MB,约 250 个包 | 单个程序,加 5 MB 的主题 |
| 构建 10 个双语页面 | 2 秒 | 5 秒 | 6 秒 | 不到 1 秒 |
| 输出体积 | 6.3 MB | 44 MB | 4.7 MB | 6.5 MB |
| 最新稳定版 | 0.43.1(2026-11-13) | 3.10.2(2026-07-10) | 1.6.4(2025-08-05) | 0.170.1(2026-11-17) |
表格背后的细节:
- Docusaurus。 对
../page.md这样的链接,它只在发出链接的文件所在目录里解析。这一点在它的源码里确认过。所以缺一篇译文,会让所有指向它的相对链接出错。默认情况下它还会去掉文件名的数字前缀:0001-sample被发布成了/rfcs/sample。它默认把.md文件当 MDX 解析;这个默认行为没有测,因为样例一开始就设成了普通 Markdown。 - VitePress。 只写在元数据里的标题,不会显示成页面上的标题。
- Hugo。 根目录下名为
index.md的文件会把整棵目录树变成一个 bundle,其他页面都不会生成。目录的入口页必须叫_index.md。 - Hextra。 它的链接处理遇到解析不了的链接会原样保留,不报错。它自带用于搜索和画图的第三方 JavaScript。
- Starlight。 依赖体积包含五个插件。画图的库占了其中很大一部分。
没有实测
- Sphinx,kitty 用的就是它。它的译文通过 gettext 存储,是按段落切开的目录文件。无法当作页面来评审。这是凭一般了解说的。
- MkDocs Material。 它处于维护模式 [官方]。它的继任者 Zensical 在 2026-11-20 到了 0.1.3 版 [官方]。
- mdBook。 它不支持多语言,也不支持元数据。
- Mintlify,MCP 和 ACP 在用。它是一项托管的商业服务。
对 cotty 的含义
- 决定用 Hugo。 JavaScript 的生成器会把几百个包带进构建,这条供应链大到无法审计。Hugo 是单个程序。
- 不用第三方主题。 模板为本项目而写。页面上的 JavaScript 并不排除。排除的是构建里的包生态。
- 对源文件的三条规则来自这次实测:
- 每个页面两种语言都要有,并且在同一次提交里。只要缺译文,每个生成器都会以某种方式出问题。
- 链接写成指向
.md文件的相对路径。它们在代码仓库的浏览界面里能用,站点会改写它们。 - 标题写在元数据里,正文没有一级标题。
- 要自己做的: 坏链接和坏锚点的检查、两种语言成对的检查,以及搜索。
这些规则写在文档体系里。
来源
- 2026-11-22 的第一手构建和测试。
- 发布日期和版本来自同一天的 npm 和 PyPI 注册表。
- Zensical 公告、mkdocs-material 发布记录
- Starlight:国际化、Pagefind:多语言搜索
没有覆盖
- 托管。
- Zola 等其他单个程序形态的生成器。