Skip to content

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) and readthedocs
  • Plugin API for extending the build (search, redirects, autogenerated content)
  • Theme ecosystem, including Material and the built-in readthedocs theme

Configuration

A minimal mkdocs.yml declares the site name, the Markdown source directory (docs/ by default), and optionally a theme:

mkdocs.yml
site_name: mypackage
theme:
  name: mkdocs
plugins:
  - search
nav:
  - Home: index.md

The 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-deploy

mkdocs 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-deploy ships docs to GitHub Pages in one command

Cons

  • No multi-format output (PDF, ePub) without third-party plugins
  • Smaller cross-reference ecosystem than Sphinx; intersphinx equivalents exist as plugins but are less mature
  • API documentation requires the mkdocstrings plugin and its language handlers
  • The Material theme is in maintenance mode; new projects should evaluate Zensical
Last updated on