22.4k stars · BSD-2-Clause · 1.6.1 (2024-08-30), confirmed on both /releases/latest and PyPI; 2.0 pre-releases continue on PyPI, the newest 2026-09-15 · Track this in Scout
Turns a folder of Markdown files into a documentation website, controlled by one settings file.
▶Repo detailsthe review · specs · pros & cons · install
What it does
You write pages in Markdown, list them in one YAML file — YAML being a plain-text format for settings — and MkDocs builds a complete static website: plain HTML files you can put on any host, with no database and nothing running on the server. A built-in development server rebuilds and reloads as you type. Themes change how it looks, plugins add behaviour, and Markdown extensions add things like footnotes and tables of contents. The newest finished release is 1.6.1, published on 30 August 2024 on both GitHub and PyPI. Version 2.0 is being built in the open: pre-release versions are on PyPI, the most recent on 15 September 2026, so the project is working, not stopped. It is BSD-2-Clause licensed. MkDocs builds files and nothing more: it does not host the site, store content, handle comments, or give anybody a place to edit.
Why it matters
Who it suits. Anyone with documentation living in a repository who wants it readable without adopting a content system. It is the easiest of the static documentation builders to start, because one command creates a working site. Skip it if you want a visual editor, or if your documentation already lives somewhere people edit in a browser.
Verdict. Still the fastest way from a folder of text to a published site, and the release gap needs explaining rather than fearing. Two years without a stable release while 2.0 pre-releases ship is a slow project, not a dead one, and the code pushed within the last year. What should shape the decision is that the theme most people actually use, squidfunk/mkdocs-material at 27.4k stars and MIT, was Edition 52 and has itself entered maintenance by its author's own statement. Both are usable and both are moving slowly. If that combination worries you, withastro/starlight at 9.2k stars and MIT, Edition 4, and rust-lang/mdBook at 22.1k stars and MPL-2.0, Edition 44, are the two liveliest alternatives.
mkdocs new .andmkdocs servegive a working, reloading site in under a minute.- The output is plain files, so hosting costs nothing and nothing can break at runtime.
- A deep plugin and theme ecosystem built over a decade, and a permissive BSD licence.
- The newest stable release is 1.6.1 from August 2024, and 2.0 is still in pre-release.
- Everything is edited as files in a repository, so non-technical colleagues will not be contributing.
- The plain theme is austere; most people add Material, which is itself in maintenance.
squidfunk/mkdocs-materialThe theme most MkDocs sites use, MIT, which turns the plain output into a polished, searchable site and is now in maintenance.
Track this in Scout
withastro/starlightA documentation framework on top of Astro, MIT, more modern and more opinionated, with built-in search and internationalisation.
Track this in Scout
rust-lang/mdBookBuilds an online book from Markdown, MPL-2.0, a single binary with no Python involved.
Track this in Scout
python3 -m venv ~/docs-env source ~/docs-env/bin/activate pip install mkdocs mkdocs new my-docs cd my-docs mkdocs serve
