Docyard vs. Docusaurus

Docusaurus is the most popular open-source documentation framework, with a large React/npm ecosystem behind it. Docyard targets a narrower audience: technical and scientific projects that already use Nix and want scholarly authoring plus multi-language API reference with as little JavaScript boilerplate as possible. See the comparisons overview for how Docyard stacks up against the other tools.

At a glance

Core philosophy and developer experience

The biggest practical difference is who maintains the JavaScript toolchain.

Docyard is Nix-native. It is consumed as a flake input. In managed mode you write only .md / .qmd files and set a handful of flake options; Docyard materializes the whole Nuxt app, wires up the content directory, runs API extraction, and builds. Content authors never touch package.json or node_modules, and the toolchain is pinned reproducibly by the flake. An explicit mode is available when you want to own a full Nuxt app and extend the theme directly.

Docusaurus is a React application you own. You scaffold a site, manage its package.json and node_modules, and keep the React/Webpack toolchain up to date over the project's lifetime. In exchange you get the full flexibility of a React app and a very large ecosystem to draw on.

If your team already runs Nix and treats documentation as a build artifact of a larger repo, Docyard removes a class of dependency upkeep. If you want maximum flexibility and aren't using Nix, Docusaurus's model is the better fit.

Technical and scholarly authoring

Docyard's reason to exist is scholarly and technical writing. The Quarto syntax pipeline is built in, not bolted on:

• Citations — @key and [@a; @b] resolve against a bibliography and render a references section.
• Numbered cross-references — @fig-, @tbl-, and @eq- references are numbered by a single numbering engine that works across files, so figure, table, and equation numbers stay consistent site-wide.
• Callouts — ::: {.callout-note} fenced divs become styled blocks.
• Math — KaTeX display and inline math, with numbered equations.
• Jupyter notebooks — .ipynb files are first-class content.

In Docusaurus the equivalent capabilities are assembled from separate remark / rehype plugins (e.g. remark-math + rehype-katex), and there is no native, cross-document numbering engine for figures, tables, and equations — that part you build yourself.

Docyard also ships a benchmarks feature (tables and charts driven from data) for projects that publish results alongside their docs.

API documentation

Docyard includes a single Go-based extractor, the docyard extract CLI, that produces normalized JSON the site renders into API pages. It supports several languages out of the box:

• Python — via griffe
• Rust — via cargo doc JSON
• TypeScript — module API extraction
• OpenAPI — from a spec file

Because extraction is one CLI feeding one renderer, multi-language projects get consistent API pages without stitching together TypeDoc, Sphinx, and bespoke build scripts. Docusaurus has no built-in API extraction; you wire up a per-language plugin (TypeDoc for TS, Sphinx/docusaurus-plugin bridges for Python, etc.) and reconcile their differing output.

Where Docusaurus is ahead

This is the honest part — and it is also Docyard's roadmap.

• Localization (i18n). Docusaurus has first-class internationalization: translation-key extraction, per-locale builds, and a documented workflow. Docyard has no built-in localization today. This is the clearest gap.
• Versioning maturity. Docyard does have built-in multi-version sites (version picker, per-version API extraction, historical content directories), but the feature is newer and not yet documented here. Docusaurus's versioning is older, widely used, and well documented. Treat Docyard's as capable but less battle-tested.
• Ecosystem and community. Docusaurus has thousands of community plugins, themes, and presets (analytics, custom search UIs, blog tooling, …) and a large support community. Docyard's ecosystem is early-stage.
• React / MDX customizability. MDX makes embedding React components in a page native, backed by the large React SSG ecosystem. Docyard supports component islands through Markdown components (MDC) on Vue/Nuxt, which is powerful but a smaller ecosystem.

Decision guide

Choose Docyard if your project is a technical or scientific codebase, already uses Nix, needs multi-language API reference (Python / Rust / TypeScript / OpenAPI), and you want scholarly authoring (citations, cross-references, math) with zero JavaScript boilerplate for content authors.

Choose Docusaurus if you need mature internationalization, want the largest plugin and theme ecosystem, have a React team eager to build custom features inside the docs, or simply aren't using Nix.

Roadmap

The gaps above are tracked as goals for Docyard:

1. Built-in localization (i18n) with a translation workflow.
2. Documentation and hardening for multi-version sites.
3. A broader plugin / theme story and customization presets.

If one of these is a blocker for you today, Docusaurus is the safer choice — revisit Docyard as these land.