Skip to content
MkDocs NG
On this page

MkDocs Alternatives Compared

MkDocs NG, ProperDocs, Zensical and upstream MkDocs, side by side.


Since upstream MkDocs 1.x stopped being developed (see Is MkDocs Still Maintained?), several projects have offered a way forward for existing MkDocs sites. This page compares them on what matters when you already have a site: whether it keeps building unchanged, and whether your plugins keep running.

Facts on this page were checked on 2026-11-01, and release versions on 2026-11-14, against each project's PyPI release history, documentation and source code; see Sources. Build times were measured on 2026-11-04. Projects change quickly, so check their documentation for the current state. If something here is wrong or out of date, please open an issue.

At a glance

  MkDocs NG MkDocs 1.6 MkDocs 2.0 pre-releases ProperDocs Zensical
What it is Maintained fork of MkDocs 1.x Last upstream 1.x release Upstream rewrite Fork of MkDocs 1.6 New generator by the Material for MkDocs team
Latest release 1.11.2 (2026-11-11) 1.6.1 (2024-08-30) 2.0.dev6 (2026-09-15) 1.6.7 (2026-03-20) 0.1.1 (2026-11-10)
PyPI package mkdocs-ng mkdocs mkdocs (--pre) properdocs zensical
Command mkdocs mkdocs mkdocs properdocs zensical
Configuration mkdocs.yml mkdocs.yml None; refuses to run when mkdocs.yml exists properdocs.yml, falls back to mkdocs.yml mkdocs.yml or zensical.toml
Runs MkDocs plugins Yes Yes No Yes No; reimplements about 30 popular ones
Runs MkDocs themes Yes Yes No Yes No; its own theme supports Material for MkDocs settings
Python 3.10+ 3.8+ 3.10+ 3.9+ 3.11+
Build of a 1,000-page site with Material for MkDocs 11.1 s 34.2 s Can't build it 32.1 s 15.9 s; 5.7 s with its cache

See Build speed for how this was measured.

Which one should I use?

  • You have an MkDocs site and want it to keep building unchanged, plugins included: MkDocs NG or ProperDocs. Both run MkDocs plugins and themes. With MkDocs NG the only change is the package name: the mkdocs command, mkdocs.yml, CI scripts and .readthedocs.yaml stay as they are. ProperDocs uses its own properdocs command.
  • Your site uses Material for MkDocs and should keep building unchanged after its end of life on 2027-05-05: MkDocs NG with MkDocs NG Material, which keeps the material theme and gets security and compatibility fixes after that date.
  • Your site uses Material for MkDocs, and only plugins that Zensical reimplements: Zensical is an option if you're ready to switch to a new generator. Check its plugin support first, since other plugins are ignored.
  • You're starting new documentation and want the MkDocs plugin ecosystem: MkDocs NG. mkdocs new creates a site to start from.
  • Staying on MkDocs 1.6.1 keeps working for now, but bugs stay unfixed and it declares support only for Python 3.8 to 3.12.
  • The MkDocs 2.0 pre-releases can't build existing sites. Avoid installing them with pip install --pre or uv --prerelease allow.

MkDocs 1.6

The last release of upstream MkDocs 1.x is 1.6.1, from August 2024. Sites and plugins built for it keep working, but bugs reported since then stay unfixed, and it declares support for Python 3.8 to 3.12 only. Plugins and themes keep installing it as a dependency, which is why MkDocs NG installs alongside it and takes precedence instead of replacing it. See Plugins, themes and the mkdocs package.

MkDocs 2.0 pre-releases

Upstream MkDocs 2.0 is a rewrite, published as pre-releases of the mkdocs package, so pip install mkdocs still installs 1.6.1 and only pip install --pre mkdocs installs 2.0. As of 2.0.dev6 it builds a directory of Markdown files with a single Jinja template (templates/base.html). It has no configuration file, plugins or themes, and it stops with an error when it finds a mkdocs.yml. Existing sites can't be built with it.

ProperDocs

ProperDocs is a fork of MkDocs 1.6 with its own package, command and configuration file name. It loads plugins and themes written for MkDocs, so existing sites can move to it by running properdocs instead of mkdocs; it also reads mkdocs.yml. Several plugins, including mkdocs-redirects, mkdocs-gen-files, mkdocs-literate-nav, mkdocs-section-index and mkdocs-rss-plugin, now depend on ProperDocs and print a warning suggesting it when run by the mkdocs command. They keep working with MkDocs NG, which turns that warning off.

Zensical

Zensical is a new static site generator from the team behind Material for MkDocs, which is in maintenance mode with critical fixes through 2027-05-05. It reads existing mkdocs.yml files and supports Material for MkDocs settings. It doesn't run MkDocs plugins: it reimplements about 30 popular ones natively and ignores the configuration of the rest. gh-deploy, get-deps and hooks aren't supported, and templates use MiniJinja instead of Jinja. It is a good fit if your site uses Material for MkDocs and only plugins it supports.

MkDocs NG

MkDocs NG continues MkDocs 1.x: same command, same mkdocs.yml, same plugin and theme APIs, so switching is a package change. On top of that it supports current Python versions (3.10 to 3.15), fixes long-standing upstream bugs, and adds features such as llms.txt output for LLMs and coding agents, a stable Python API, and built-in themes that load nothing from CDNs. Every change is tested by building sites with around 30 popular plugins, themes and Markdown extensions. See Switching to MkDocs NG.

Build speed

We built the same generated site with each tool: Markdown pages with headings, lists, tables, code blocks and links between pages, in sections of 49 pages. Every tool builds all the pages and a search index, with the same Markdown extensions where it has them. Times are the median of 5 clean builds for the Python tools and 3 for the others, one tool after another, on a 4-core Linux machine with 16 GB of memory, Python 3.13 and Node.js 22, measured on 2026-11-04. The script is benchmarks/compare.py, so you can repeat it on your own machine.

Clean build of 1,000 pages

Tool Theme Time
MkDocs NG 1.11.0 mkdocs 8.8 s
MkDocs NG 1.11.0 Material for MkDocs (mkdocs-ng-material 9.8.0) 11.1 s
MkDocs NG 1.11.0 Sumi 0.2.0 12.2 s
Zensical 0.0.74 Its own, based on Material for MkDocs 15.9 s; 5.7 s with its cache
MkDocs 1.6.1 mkdocs 16.4 s
ProperDocs 1.6.7 mkdocs 16.9 s
Sphinx 9.2, 4 processes Alabaster 23.5 s
ProperDocs 1.6.7 Material for MkDocs 9.8.0 32.1 s
Astro Starlight 0.42.8 Its own 32.9 s; 21.8 s with its cache
MkDocs 1.6.1 Material for MkDocs 9.8.0 34.2 s
VitePress 1.6.4 Its own 85.4 s
Docusaurus 3.10.2 Its own 106.6 s; 39.3 s with its cache

Each tool ran with its default settings. Zensical, Starlight and Docusaurus keep caches between builds (in .cache, node_modules/.astro and node_modules/.cache); the first time is with the cache removed before the build, the second with it kept, after a build with no changes. MkDocs NG has no cache between builds. Compare like with like: Zensical's theme is based on Material for MkDocs, so the closest MkDocs NG time is the one with Material. ProperDocs is a fork of MkDocs 1.6 and builds as fast as it: the difference between them is within the variation between runs.

Clean build of 5,000 pages

One run of each, measured on 2026-11-02 (ProperDocs on 2026-11-04).

Tool Theme Time
Zensical 0.0.74, cache kept Its own 59.2 s
MkDocs NG 1.11.0rc1 mkdocs 59.6 s
MkDocs NG 1.11.0rc1 Sumi 0.2.0 67.6 s
MkDocs NG 1.11.0rc1 Material for MkDocs (mkdocs-ng-material 9.8.0) 134.5 s
Zensical 0.0.74, cache cleared Its own 185.7 s
MkDocs 1.6.1 mkdocs 340.0 s
ProperDocs 1.6.7 mkdocs 341.2 s

With Material for MkDocs every page holds the whole navigation, so this site is more than 4 GB of HTML, which is most of the time it takes. Zensical's cache for it takes another 8 GB.

Showing an edit in serve

How long after saving a page of the 1,000-page site the development server serves the changed page, median of 5 edits, measured on 2026-11-04:

Tool Theme Time
Zensical 0.0.74 Its own, based on Material for MkDocs 1.2 s
MkDocs NG 1.11.0 mkdocs 1.2 s
MkDocs NG 1.11.0 Sumi 0.2.0 1.8 s
MkDocs NG 1.11.0 Material for MkDocs (mkdocs-ng-material 9.8.0) 2.7 s
ProperDocs 1.6.7 mkdocs 17.9 s
MkDocs 1.6.1 mkdocs 18.6 s
MkDocs 1.6.1 Material for MkDocs 9.8.0 35.9 s
ProperDocs 1.6.7 Material for MkDocs 9.8.0 37.3 s

Zensical rebuilds only the pages that changed. MkDocs NG runs the plugin events for the whole site, because a plugin can change any page when one changes, but reuses the rendered Markdown and HTML of the pages that didn't change. MkDocs 1.6.1 and ProperDocs build the whole site again.

Sources

Esc
↵ to open ↑↓ to move Esc to close
Keyboard shortcuts
Ctrl K /
Open search and commands
t
Toggle dark mode
[ ]
Previous / next page
j k
Previous / next heading
?
Show this help