本页内容
  1. 发现
  2. 方法
  3. 结果
  4. 没有实测
  5. 对 cotty 的含义
  6. 来源
  7. 没有覆盖

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

这些规则写在文档体系里。

来源

没有覆盖

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