MkDocs — Python Documentation Generator

Overview

MkDocs turns a folder of Markdown files and one mkdocs.yml into a static documentation site. Most sites pair it with Material for MkDocs (mkdocs-material), which adds the theme, search, navigation features, tags, blog and social cards. The ecosystem changed in 2025–2026, so check the state before starting (as of October 2026):

MkDocs 1.6.1 (August 2024) is still the latest stable release; pip install mkdocs installs it. There has been no 1.x release since.
MkDocs 2.0 exists only as pre-releases (2.0.dev6, installed only with pip install --pre). It is a rewrite: according to the Material for MkDocs maintainers it drops the plugin system, replaces the theming API and does not read mkdocs.yml (2.0.dev6 stops with an error when it finds one), so no existing Material site builds on it.
Material for MkDocs 9.7 is in maintenance mode since November 2025: 9.7.0 was the last feature release (it made the former Insiders features free), and the team promised critical bug and security fixes for at least 12 months, later extended to May 5, 2027, when the theme reaches end of life. It requires mkdocs>=1.6,<2.
Zensical (zensical, MIT) is the successor from the same team. It reads an existing mkdocs.yml, reimplements the popular plugins natively and is released about once a week. It is at 0.0.67, a series its own team calls alpha; they have announced 0.1.0, the first release line they describe as dependable, for November 5, 2026.
ProperDocs (properdocs) is a community fork of MkDocs 1.x that aims to be a drop-in replacement.

Instructions

What to use today

Existing Material for MkDocs site: keep building it, with exact version pins. Nothing forces a move, but it will get no new features. Build the same mkdocs.yml with Zensical alongside and switch when every plugin you depend on is supported (Example 2).
New site: start with Zensical if its supported plugin list covers you; pin the exact version because it is pre-1.0. Choose Material for MkDocs 9.7 if you need a third-party MkDocs plugin Zensical does not replace, and accept that it is frozen.
Never install MkDocs with --pre or leave mkdocs unpinned in a Material project.