On this page
  1. Findings
  2. Method
  3. Results
  4. Not tested
  5. What this means for cotty
  6. Sources
  7. Not covered

Which generator should build the cotty site? Four were built against the same sample. By function, Starlight fit best. Hugo was chosen: it is one program with no dependency on the JavaScript package ecosystem, and what it lacks can be closed with our own templates and scripts.

Findings

Method

The sample was a set of paired English and Chinese pages taken from cotty’s own notes: a product page, an RFC with metadata, and a post. Links were written as relative paths to .md files, the way a repository browser follows them. Each generator built the sample. Then errors were introduced: a missing translation, a link to a missing page, a link to a missing anchor, and an invalid metadata value.

Everything in the table is a first-hand result from 2026-11-22. The versions were Starlight 0.43.1 on Astro 7.4, Docusaurus 3.10.2, VitePress 1.6.4, and Hugo 0.170.1 with the Hextra theme.

Results

Check Starlight Docusaurus VitePress Hugo with Hextra
Side-by-side folders en/ and zh/ Yes No. Translations must be in its own i18n/… folder Yes Yes
Rewrites relative links to site addresses With a third-party plugin Built in Built in By the theme
Stops broken links and broken anchors With a third-party plugin, both Built in, both Broken links only Neither
One translation missing Falls back to English with a notice. Links to that page break Relative links fail and the build stops The build stops Not tested
Diagrams from text (mermaid) Third-party plugin Official plugin Third-party plugin, not updated since 2024-09 In the theme
Search in Chinese Built in, split by word Third-party plugin, split by word Built in, but Chinese is not split In the theme, split by character
Typed metadata Built in. An invalid value stops the build No No No
What the sources must give way to Nothing Two defaults must be turned off The title must be in the body. Content must be inside the project folder The home page must be named _index.md
Dependencies 432 MB, about 500 packages 561 MB, about 1200 packages 278 MB, about 250 packages One program, and a 5 MB theme
Build of 10 bilingual pages 2 s 5 s 6 s Under 1 s
Size of the output 6.3 MB 44 MB 4.7 MB 6.5 MB
Latest stable release 0.43.1 (2026-11-13) 3.10.2 (2026-07-10) 1.6.4 (2025-08-05) 0.170.1 (2026-11-17)

Details behind the table:

  • Docusaurus. It resolves a link such as ../page.md only from the folder of the linking file. This was confirmed in its source code. So a missing translation breaks every relative link to it. By default it also strips a numeric prefix from file names: 0001-sample was published as /rfcs/sample. It parses .md files as MDX by default; this default was not tested, because the sample set it to plain Markdown from the start.
  • VitePress. A title given only in the metadata is not shown as a heading on the page.
  • Hugo. A file named index.md at the root turns the whole tree into one bundle, and no other page is built. The landing page of a folder must be _index.md.
  • Hextra. Its link handling leaves a link it cannot resolve as it is, without an error. It ships third-party JavaScript for search and for diagrams.
  • Starlight. The dependency size includes five plugins. The diagram library is a large part of it.

Not tested

  • Sphinx, which kitty uses. Its translations are stored through gettext, as catalog files cut by paragraph. They cannot be reviewed as pages. This is from general knowledge.
  • MkDocs Material. It is in maintenance mode [official]. Its successor Zensical had reached version 0.1.3 on 2026-11-20 [official].
  • mdBook. It has no support for several languages or for metadata.
  • Mintlify, which MCP and ACP use. It is a hosted commercial service.

What this means for cotty

  • The decision is Hugo. The JavaScript generators bring hundreds of packages into the build, which is a supply chain too large to audit. Hugo is one program.
  • No third-party theme. The templates are written for this project. JavaScript on the pages is not excluded. What is excluded is the package ecosystem in the build.
  • Three rules for the sources follow from the tests:
    • Both languages exist for every page, in the same commit. Every generator misbehaved in some way when a translation was missing.
    • Links are relative paths to .md files. They work in a repository browser, and the site rewrites them.
    • The title is in the metadata, and the body has no level-one heading.
  • What we build ourselves: the check for broken links and anchors, the check that both languages are paired, and search.

These rules are stated in Documentation system.

Sources

Not covered

  • Hosting.
  • Zola and other generators that are a single program.