Docyard vs. MkDocs
A realistic comparison of Docyard and MkDocs (with Material for MkDocs).
Docyard vs. MkDocs
MkDocs, almost always paired with Material for MkDocs, is a hugely popular Python-based, Markdown-only documentation generator. It is loved for being simple, fast, and good-looking out of the box.
At a glance
| Dimension | Docyard | MkDocs (Material) |
|---|---|---|
| Authoring format | Markdown, Quarto (.qmd), Jupyter (.ipynb) | Markdown (Python-Markdown extensions) |
| Callouts | Built-in | Built-in (Material admonitions) |
| Search | Local / Pagefind / Algolia | Built-in (very good) |
| Citations & cross-refs | Built-in, numbered, cross-document | Not native (no numbered cross-references) |
| Math | Built-in (KaTeX) | Plugin (arithmatex + MathJax/KaTeX) |
| Python API | docyard extract (griffe) | mkdocstrings (also griffe) |
| Multi-language API | Python, Rust, TypeScript, OpenAPI in one CLI | Python-focused; others via separate tools |
| Toolchain | Nix flake, Nuxt frontend | Python/pip |
| Localization | Not built in (roadmap) | Plugin (mkdocs-static-i18n) |
| Ecosystem | Early-stage | Large, active plugin ecosystem |
Be honest about the overlap
Material for MkDocs is feature-rich, so several things are not Docyard differentiators here:
- Admonitions (Material) cover the same ground as Docyard's callouts.
- Search in Material is excellent and built in.
- Python API extraction in MkDocs is
mkdocstrings, which uses griffe — the same library Docyard uses for Python. So Docyard's Python extraction is not unique; the difference is that Docyard runs Python, Rust, TypeScript, and OpenAPI through one extractor.
Where Docyard wins
- Numbered cross-references and citations. MkDocs has no native numbered figure/table/equation cross-referencing engine and no built-in bibliography. Docyard does both, across documents. This is its clearest edge here.
- Quarto and Jupyter as first-class formats.
.qmdand.ipynbfiles work like any other page. - One multi-language API extractor. Rust, TypeScript, and OpenAPI reference alongside Python from a single CLI, without bolting on separate tools.
- Nix-native reproducibility. A pinned flake toolchain; authors in managed mode touch only content files.
Where MkDocs wins
- Simplicity and speed. Minimal config, very fast builds, gentle learning curve. For straightforward Markdown docs it is hard to beat.
- Material polish. A mature, highly configurable theme with features (tabs, annotations, social cards, instant navigation) refined over years.
- Ecosystem. A large catalogue of plugins.
- Localization. A working i18n story via plugin; Docyard has none yet.
Decision guide
Choose Docyard if you need scholarly features (numbered cross-references, citations, math) without assembling plugins, want multi-language API reference from one tool, or already use Nix.
Choose MkDocs if you want the simplest possible Markdown workflow, the
polished Material theme, a mature plugin ecosystem, and your API needs are
Python-centric (where mkdocstrings is excellent).