# 双语文档站点的生成器选型

地址: https://nowa.im/cotty/zh/research/studies/2026-11-docs-site-generators/  
创建: 2026-11-22

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` 文件的相对路径。它们在代码仓库的浏览界面里能用，站点会改写它们。
  - 标题写在元数据里，正文没有一级标题。
- **要自己做的：** 坏链接和坏锚点的检查、两种语言成对的检查，以及搜索。

这些规则写在[文档体系](https://nowa.im/cotty/zh/handbook/documentation/)里。

## 来源

- 2026-11-22 的第一手构建和测试。
- 发布日期和版本来自同一天的 npm 和 PyPI 注册表。
- [Zensical 公告](https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/)、[mkdocs-material 发布记录](https://github.com/squidfunk/mkdocs-material/releases)
- [Starlight：国际化](https://starlight.astro.build/guides/i18n/)、[Pagefind：多语言搜索](https://pagefind.app/docs/multilingual/)

## 没有覆盖

- 托管。
- Zola 等其他单个程序形态的生成器。
