MkDocs is a static site generator that builds documentation websites from Markdown source files. The project is configured through a single `mkdocs.yml` YAML file. It ships with a built-in development server, two built-in themes (`mkdocs` and `readthedocs`), and a plugin and theme ecosystem that extends those defaults. Common additions include the [Material]({{ }}) theme and the [mkdocstrings]({{ }}) plugin for autogenerated API documentation.

What is the difference between MkDocs and Sphinx?

MkDocs is Markdown-only and uses a static YAML configuration file. [Sphinx]({{ }}) defaults to reStructuredText (with optional Markdown via MyST) and uses an executable Python `conf.py`. Sphinx has a deeper extension ecosystem, especially around API documentation and multi-format output (PDF, ePub). MkDocs is generally faster to set up for prose-first projects whose contributors already know Markdown.

How do I install MkDocs?

Install MkDocs with `uv add --group docs mkdocs` to add it to a `[dependency-groups]` docs group, or `pip install mkdocs` for a global install. Run `mkdocs new my-project` to scaffold a new site, edit `mkdocs.yml` and the files under `docs/`, then run `mkdocs serve` for live preview or `mkdocs build` to render to `site/`.

Can MkDocs generate API documentation from docstrings?

MkDocs does not generate API documentation by itself. Install the [mkdocstrings]({{ }}) plugin (with the `mkdocstrings-python` handler for Python projects) and inject API reference into any Markdown page using the `::: module.path` syntax. mkdocstrings reads docstrings in Google, NumPy, or Sphinx format.

What themes work with MkDocs?

MkDocs ships with two built-in themes: `mkdocs` (the default) and `readthedocs`. The most popular third-party theme is [Material for MkDocs]({{ }}), which adds search, dark mode, code annotations, and a wide configuration surface. Other community themes are listed in the MkDocs catalog.

MkDocs: Markdown Documentation for Python Projects

by Tim Hopper

Documentation

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 1.6.1 (August 30, 2024) is the current stable release; license is BSD-2-Clause. Install via uv add --group docs mkdocs or pip install mkdocs. The maintainers are also developing MkDocs 2.0 as a ground-up rewrite alongside Zensical.

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. For an API-first project or one that needs PDF output and a richer cross-reference system, see the Sphinx reference.

Key Features

Markdown-only source format (CommonMark plus Python-Markdown 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: material
plugins:
  - search
  - mkdocstrings
nav:
  - Home: index.md
  - API: api.md

The nav block defines the sidebar navigation. Pages without an nav entry are still rendered but do not appear in the menu.

Common Commands

# Scaffold a new site in a directory
mkdocs new 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 entered maintenance mode in early 2026; greenfield projects should track Zensical as the proposed successor

Learn More

MkDocs Documentation
GitHub Repository
MkDocs Catalog (themes and plugins)
Material for MkDocs (popular theme)
mkdocstrings (API documentation plugin)

Last updated on April 29, 2026

Material for MkDocs mkdocstrings

Please submit corrections and feedback...