# mkdocstrings: Autogenerate API Documentation in MkDocs


mkdocstrings is a [MkDocs](https://pydevtools.com/handbook/reference/mkdocs.md) 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.

> [!NOTE]
> mkdocstrings 1.0.4 and the Python handler `mkdocstrings-python` 2.0.3 are the current stable releases (April 2026). Both are licensed ISC. Install with `uv add --group docs 'mkdocstrings[python]'`.

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

## Configuration

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

```yaml {filename="mkdocs.yml"}
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:

```markdown {filename="docs/api.md"}
# 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

| Handler package | Language | Notes |
|---|---|---|
| `mkdocstrings-python` | Python | The standard Python handler; built on [Griffe](https://mkdocstrings.github.io/griffe/) |
| `mkdocstrings-crystal` | Crystal | Community handler |
| `mkdocstrings-c` | C | Community handler |
| `mkdocstrings-shell` | Shell scripts | Community handler |

The Python handler is the standard reference for most users. The full list lives at [mkdocstrings.github.io](https://mkdocstrings.github.io/#handlers).

## 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](https://mkdocstrings.github.io/)
* [GitHub Repository](https://github.com/mkdocstrings/mkdocstrings)
* [Python Handler Documentation](https://mkdocstrings.github.io/python/)
* [Griffe](https://mkdocstrings.github.io/griffe/) (the static analysis library underneath)
* [MkDocs Reference](https://pydevtools.com/handbook/reference/mkdocs.md)