Docyard vs. Starlight
A comparison of Docyard and Starlight, Astro's documentation theme.
Docyard vs. Starlight
Starlight is the official documentation theme for Astro. It is modern, fast, accessible, and lets you drop components from any UI framework (React, Vue, Svelte, …) into Markdown via Astro's islands. It is an excellent general-purpose docs theme.
At a glance
| Dimension | Docyard | Starlight |
|---|---|---|
| Runtime / tech | Nix + Nuxt (Vue) | Astro (any framework via islands) |
| Authoring format | Markdown, Quarto (.qmd), Jupyter (.ipynb) | Markdown, MDX |
| Citations & cross-refs | Built-in, numbered, cross-document | Not built in |
| Math | Built-in (KaTeX) | Plugin (remark-math + rehype-katex) |
| API extraction | Built-in: Python, Rust, TypeScript, OpenAPI | None (community plugins for some) |
| Search | Local / Pagefind / Algolia | Built-in (Pagefind) |
| Localization | Not built in (roadmap) | Built-in (first-class i18n) |
| Toolchain | Nix flake (no node_modules for authors) | Node.js / package.json |
| Ecosystem | Early-stage | Growing (Astro integrations) |
Where Docyard wins
- Scholarly authoring. Starlight has no native citations, bibliographies, or numbered cross-document references. Docyard is built around them.
- API extraction. Starlight has none built in; Docyard extracts Python, Rust, TypeScript, and OpenAPI from one CLI.
- Quarto and Jupyter formats. First-class in Docyard.
- Nix-native reproducibility. Managed mode keeps authors out of
node_modules.
Where Starlight wins
- First-class i18n. Built-in localized routing and UI translations — one of Docyard's clearest gaps. If multilingual docs matter, this is decisive.
- Framework-agnostic islands. Embed React, Vue, Svelte, or Solid components in the same site. Docyard's components are Vue/Nuxt.
- Astro ecosystem and performance. Minimal-JS output by default, a growing integration ecosystem, and excellent accessibility defaults.
- Maturity. A polished, well-documented, widely adopted theme.
Decision guide
Choose Docyard if you need scholarly authoring or multi-language API reference, or want a Nix-native content workflow.
Choose Starlight if you need first-class internationalization, want to mix UI frameworks via Astro islands, or want a fast, polished general-purpose docs site and do not need citations, cross-references, or generated API reference.