Comparisons
How Docyard compares to Docusaurus, Sphinx, MkDocs, VitePress, Starlight, and GitBook — and how to choose.
Comparisons
There are many good documentation tools. Docyard is not trying to replace all of them — it targets a specific niche: technical and scientific projects that already use Nix and want scholarly authoring plus multi-language API reference with little JavaScript boilerplate.
These pages are meant to help you choose, and they double as an honest map of where Docyard is still catching up. Each comparison has its own "where Docyard wins / where the other tool wins" section, because the honest answer differs a lot by competitor — Docyard's edge is large against generic site generators and narrow against mature scholarly tools like Sphinx.
- vs. Docusaurus — the popular React/MDX portal
- vs. Sphinx — the scientific-Python incumbent
- vs. MkDocs — Material for MkDocs, the Python favorite
- vs. VitePress — the fast Vue/Vite generator
- vs. Starlight — Astro's docs theme
- vs. GitBook — the hosted, WYSIWYG SaaS
The landscape at a glance
| Feature | Docyard | Docusaurus | Sphinx | MkDocs (Material) | VitePress | Starlight | GitBook |
|---|---|---|---|---|---|---|---|
| Runtime / tech | Nix + Nuxt (Vue) | React | Python | Python | Vue / Vite | Astro | SaaS (hosted) |
| Authoring | Markdown, Quarto, Jupyter | Markdown, MDX | reST / MyST-Markdown | Markdown | Markdown | Markdown, MDX | WYSIWYG |
| Citations & cross-refs | Built-in | Manual plugins | Built-in (numfig, bibtex) | Plugin | No | No | No |
| Math | Built-in (KaTeX) | Plugin | Built-in (MathJax) | Plugin | Plugin | Plugin | Limited |
| API extraction | Built-in: Py, Rust, TS, OpenAPI | Plugin per lang | Built-in (autodoc, Python) | Plugin (mkdocstrings) | No | No | OpenAPI only |
| Search | Local / Pagefind / Algolia | Local + Algolia | Built-in | Built-in | Local + Algolia | Built-in (Pagefind) | Built-in (hosted) |
| Versioning | Built-in (newer) | Built-in (mature) | Via tooling | Plugin (mike) | Manual | Manual | Built-in (hosted) |
| Localization (i18n) | Not built in (roadmap) | Built-in | Built-in (gettext) | Plugin | Built-in | Built-in | Built-in |
| Hosting | Static (self-host) | Static | Static | Static | Static | Static | SaaS |
| Ecosystem | Early-stage | Large | Very large | Large | Growing | Growing | Commercial |
The rest of these pages explain the trade-offs behind each row.
What Docyard brings to every comparison
The Docyard column above is the same on every page. Its consistent strengths:
- Nix-native, reproducible toolchain. Consumed as a flake input; in managed
mode content authors write only
.md/.qmdfiles and never touchnode_modules. - Scholarly authoring built in. Citations, cross-document numbered
references (
@fig-/@tbl-/@eq-), callouts, and KaTeX math, with Quarto (.qmd) and Jupyter (.ipynb) as first-class formats. - One multi-language API extractor. A single Go CLI (
docyard extract) covers Python (griffe), Rust (rustdoc), TypeScript, and OpenAPI, feeding one consistent renderer.
And its consistent gaps:
- No localization (i18n) — the clearest missing feature.
- Small ecosystem and a newer versioning feature relative to the established tools.
See the roadmap on the Docusaurus page for how these gaps are being tracked.