# 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 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](https://www.mkdocs.org/about/release-notes/) as a ground-up rewrite alongside [Zensical](https://pydevtools.com/handbook/reference/mkdocs-material.md#zensical-and-the-2026-roadmap).

## 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](https://pydevtools.com/handbook/reference/sphinx.md).

## 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](https://pydevtools.com/handbook/reference/mkdocs-material.md) 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:

```yaml {filename="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

```bash
# 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](https://github.com/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](https://zensical.org/) as the proposed successor

## Learn More

* [MkDocs Documentation](https://www.mkdocs.org/)
* [GitHub Repository](https://github.com/mkdocs/mkdocs)
* [MkDocs Catalog](https://github.com/mkdocs/catalog) (themes and plugins)
* [Material for MkDocs](https://pydevtools.com/handbook/reference/mkdocs-material.md) (popular theme)
* [mkdocstrings](https://pydevtools.com/handbook/reference/mkdocstrings.md) (API documentation plugin)
* [How to Set Up Documentation for a Python Package with Sphinx or MkDocs](https://pydevtools.com/handbook/how-to/how-to-set-up-documentation-for-a-python-package.md) scaffolds an MkDocs site inside a uv project
* [Read the Docs](https://pydevtools.com/handbook/reference/read-the-docs.md) is the standard hosting platform for MkDocs output
* [How to Build Read the Docs with uv](https://pydevtools.com/handbook/how-to/how-to-build-read-the-docs-with-uv.md) configures `.readthedocs.yaml` for uv-based builds