# Site generators for a bilingual documentation site

Address: https://nowa.im/cotty/research/studies/2026-11-docs-site-generators/  
Created: 2026-11-22

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](https://nowa.im/cotty/handbook/documentation/).

## 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](https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/), [mkdocs-material releases](https://github.com/squidfunk/mkdocs-material/releases)
- [Starlight: internationalization](https://starlight.astro.build/guides/i18n/), [Pagefind: multilingual search](https://pagefind.app/docs/multilingual/)

## Not covered

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