Site generators for a bilingual documentation site
On this page
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.mdonly 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-samplewas published as/rfcs/sample. It parses.mdfiles 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.mdat 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
.mdfiles. 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
- First-hand builds and tests on 2026-11-22.
- Release dates and versions from the npm and PyPI registries on the same day.
- Zensical announcement, mkdocs-material releases
- Starlight: internationalization, Pagefind: multilingual search
Not covered
- Hosting.
- Zola and other generators that are a single program.