mkdocstrings

1.0.3 · active · verified Thu Apr 09

mkdocstrings is an MkDocs plugin that generates automatic documentation from source code, providing an alternative to Sphinx. It leverages 'handlers' (like mkdocstrings-python) to parse different language sources and render them within your MkDocs site. The current version is 1.0.3, with frequent patch releases and occasional minor/major feature releases.

Warnings

breaking Version 1.0.0 introduced significant breaking changes to the `BaseHandler` API. If you have custom handlers or extend `mkdocstrings` programmatically, your code will likely break.
Fix: Review the changelog for 1.0.0. Key changes include removal of `BaseHandler.name`, `BaseHandler.domain`, `BaseHandler.fallback_config`, and changes to `BaseHandler.__init__` parameters. Update your custom handler implementations accordingly.
deprecated Importing public objects directly from submodules (e.g., `mkdocstrings.handlers.python.PythonHandler`) was deprecated in 0.28.3 and will raise errors in v1.x. Public objects should now be imported from the top-level `mkdocstrings` module.
Fix: Consult the official documentation for the canonical import paths of public objects. Where possible, import directly from `mkdocstrings`.
gotcha mkdocstrings requires a language-specific 'handler' to actually parse and document code (e.g., for Python, `mkdocstrings-python`). Installing `mkdocstrings` alone is often not enough.
Fix: Install the appropriate handler for your language. For Python, use `pip install "mkdocstrings[python]"` or `pip install mkdocstrings-python`.
gotcha Incorrect or missing plugin configuration in `mkdocs.yml` is a common source of errors. Users often forget to list `mkdocstrings` under the `plugins:` section or misconfigure handler-specific options like `paths`.
Fix: Ensure `mkdocstrings` is correctly listed under `plugins:` in your `mkdocs.yml`. Verify that handler-specific options (e.g., `python.paths`) point to the correct directories containing your source code.
gotcha When using `mkdocstrings` with `mkdocs-autorefs`, the order of plugins in `mkdocs.yml` matters. `mkdocstrings` should generally be listed *before* `mkdocs-autorefs` to ensure that references are properly resolved.
Fix: Configure your `mkdocs.yml` `plugins` section as follows: `plugins: - mkdocstrings - mkdocs-autorefs`.

Install

pip install "mkdocstrings[python]" Install with Python handler
pip install mkdocstrings Install core only (no handler)

Imports

MkdocstringsPlugin
```
from mkdocstrings.plugin import MkdocstringsPlugin
```
This is for programmatic interaction with the plugin class itself, which is rare for typical users. Most interaction is via mkdocs.yml configuration.

Quickstart

To quickly get started, install mkdocstrings with the Python handler. Create a `mkdocs.yml` file, add the `mkdocstrings` plugin, and configure the Python handler to point to your source code directory (e.g., `src`). Then, in your Markdown files, use the `:::` syntax to reference your Python objects. This example shows how to document a function `greet` from `src/my_module.py`.

# mkdocs.yml
site_name: My Awesome Project
theme: material

plugins:
  - mkdocstrings: # Enable the mkdocstrings plugin
      handlers:
        python:
          paths: [src] # Tell the Python handler where to find your code

# src/my_module.py
def greet(name: str) -> str:
    """
    Greets a person by their name.

    Parameters:
        name: The name of the person to greet.

    Returns:
        A personalized greeting string.
    """
    return f"Hello, {name}!"

# docs/index.md
# Welcome

This is the main documentation page.

## API Reference

::: src.my_module.greet
    options:
      show_source: false

view raw JSON →