MkDocs: Markdown Documentation for Python Projects
MkDocs is a static site generator that builds documentation websites from Markdown source files. A project’s structure, navigation, theme, and plugins are declared in a single mkdocs.yml file at the repo root.
Note
MkDocs is licensed BSD-2-Clause. Install via uv add --group docs mkdocs or pip install mkdocs. Zensical is a separate project from the Material for MkDocs team; see the Material migration guidance.
When to use MkDocs
Pick MkDocs when contributors prefer Markdown over reStructuredText, when the documentation is prose-first (tutorials, how-to guides, conceptual explanations) rather than API-first, or when the project’s audience already writes Markdown for READMEs and changelogs. Compare MkDocs with Sphinx, Great Docs, and Zensical in Which Python documentation tool should I use?.
Key Features
- Markdown source parsed by Python-Markdown, with configurable extensions
- Single-file YAML configuration (
mkdocs.yml) - Built-in dev server with auto-reload (
mkdocs serve) - Built-in themes:
mkdocs(default) andreadthedocs - Plugin API for extending the build (search, redirects, autogenerated content)
- Theme ecosystem, including Material and the built-in
readthedocstheme
Configuration
A minimal mkdocs.yml declares the site name, the Markdown source directory (docs/ by default), and optionally a theme:
site_name: mypackage
theme:
name: mkdocs
plugins:
- search
nav:
- Home: index.mdThe nav block defines the sidebar navigation. Pages without a nav entry are still rendered but do not appear in the menu.
Common Commands
These commands assume MkDocs is on PATH. When installed in a uv dependency group, prefix them with uv run --group docs.
# Scaffold a new site in a directory
mkdocs new mypackage
cd mypackage
# Build to site/
mkdocs build
# Run the dev server with live reload
mkdocs serve
# Deploy to GitHub Pages
mkdocs gh-deploymkdocs gh-deploy pushes the built site/ directory to a gh-pages branch and is the simplest path to GitHub Pages hosting.
Pros
- Lower barrier to entry than Sphinx for Markdown-first projects
- Single YAML config is easy to read and review
- Live-reload dev server is built in (no separate watcher needed)
- Plugin and theme ecosystem with hundreds of community entries in the MkDocs catalog
mkdocs gh-deployships docs to GitHub Pages in one command
Cons
- No multi-format output (PDF, ePub) without third-party plugins
- Smaller cross-reference ecosystem than Sphinx;
intersphinxequivalents exist as plugins but are less mature - API documentation requires the
mkdocstringsplugin and its language handlers - The Material theme is in maintenance mode; new projects should evaluate Zensical