mkdocstrings: Autogenerate API Documentation in MkDocs

mkdocstrings is a MkDocs plugin that generates API documentation from source code and injects it directly into Markdown pages. The base plugin is language-agnostic; concrete language support ships as separate handler packages.

When to use mkdocstrings

Use mkdocstrings whenever a MkDocs project needs autogenerated API reference. It is the standard companion plugin for any MkDocs site documenting a Python library. Projects whose documentation is already in Sphinx typically use Sphinx’s built-in autodoc extension instead.

Key Features

• Language-agnostic core with pluggable handlers (Python is most common)
• Reads Google-style, NumPy-style, and Sphinx-style docstrings
• Inline injection: drop ::: module.path into any Markdown file to render that object
• Cross-references between API and prose pages, and across mkdocstrings sites
• Source links: optional [source] link from each documented object
• Theme integration with Material for MkDocs (the default styling target)

Configuration

Add the plugin to mkdocs.yml and configure handler options under handlers:

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google
            show_source: true
            show_root_heading: true
            members_order: source

In any Markdown page, inject documentation with the ::: directive:

# API Reference

::: mypackage.greet

The build runs the plugin, which imports mypackage.greet, walks its public attributes, and renders Markdown for each function and class. The result appears as a normal MkDocs page.

Handlers

The Python handler is the standard reference for most users. The full list lives at mkdocstrings.github.io.

Pros

• The standard way to add API reference to a MkDocs site
• Language-agnostic core opens the door for non-Python projects
• Supports the three most common Python docstring formats
• Theme integration with Material for MkDocs
• Inline ::: syntax makes API blocks easy to mix with prose

Cons

• Requires importing the documented package at build time, which means the package must be installable in the docs environment
• Smaller ecosystem of extensions and signal options than Sphinx autodoc
• Cross-references across sites are less mature than Sphinx intersphinx
• Each language handler is a separate maintenance surface

Learn More

• mkdocstrings Documentation
• GitHub Repository
• Python Handler Documentation
• Griffe (the static analysis library underneath)
• MkDocs Reference