2026-10-192026-10-19

MkDocstrings ⚓︎

Automatic documentation from sources, for MkDocs. Project documentation with Markdown.

Sunsetting Gitter and Related Links.

Come have a chat or ask questions on our Gitter channel. Sunsetting Gitter: Towards Efficient Community Engagement. Go to: Handlers Documentation Go to: Theming Documentation Go to: Usage Documentation

MkDocstrings extra Documentation

👉 MkDocstrings-Handlers

👉 MkDocstrings-Theming

👉 MkDocstrings-Usage

Features - Installation - Quick usage

Features⚓︎

Language-agnostic
View Handlers

Written in Python but works with any language via handlers. Supports C, Crystal, Python, MATLAB, and more.
Multiple Themes
View Theming

Supports Material, ReadTheDocs, and MkDocs themes. Each handler can offer unique styling options.
Internal Refs
View Usage

Reference headings across pages using [identifier][]. Note: Since v0.15, you must opt in for MD headers.
External Refs
View Usage

Reference API items from other libraries using inventory files, similar to Sphinx's intersphinx.
Inline Injection
View Usage

Inject documentation anywhere using identifier syntax followed by an indented YAML block.
Configuration
View Options

Flexible setup with global options in mkdocs.yml and local overrides for each instruction.

Standard Defaults

Drop the plugin in and enjoy. Designed to work out of the box with sensible, production-ready settings.

Used By⚓︎

Used By

mkdocstrings is used by well-known companies, projects and scientific teams:

Repositories that depend on mkdocstrings.

Ansible, Apache, FastAPI, Google, IBM, Jitsi, Microsoft, NVIDIA, Prefect, Pydantic, Textual, and more...

Installation⚓︎

Installation

The mkdocstrings package doesn't provide support for any language: it's just a common base for language handlers.
It means you likely want to install it with one or more official handlers, using extras.
For example, to install it with Python support:

pip install 'mkdocstrings[python]'

Alternatively, you can directly install the language handlers themselves, which depend on mkdocstrings anyway:

pip install mkdocstrings-python

This will give you more control over the accepted range of versions for the handlers themselves.

See the official language handlers.

Conda

With conda:

conda install -c conda-forge mkdocstrings mkdocstrings-python

Quick Usage⚓︎

Quick Usage

In mkdocs.yml:

site_name: "My Library"

theme:
  name: "material"

plugins:
- search
- mkdocstrings

In one of your markdown files:

# Reference

::: my_library.my_module.my_class

See the Usage section of the docs for more examples!

Sponsors⚓︎

Silver sponsors

Bronze sponsors

And 7 more private sponsor(s).

Example - just type hints

from typing import Annotated, Literal

from annotated_types import Gt

from pydantic import BaseModel


class Fruit(BaseModel):
    name: str  # (1)
    color: Literal['red', 'green']  # (2)
    weight: Annotated[float, Gt(0)]  # (3)
    bazam: dict[str, list[tuple[int, bool, float]]]  # (4)


print(
    Fruit(
        name='Apple',
        color='red',
        weight=4.2,
        bazam={'foobar': [(1, True, 0.1)]},
    )
)
# > name='Apple' color='red' weight=4.2 bazam={'foobar': [(1, True, 0.1)]}

Performance Example - Pydantic vs. dedicated code

In general, dedicated code should be much faster than a general-purpose validator, but in this example Pydantic is >300% faster than dedicated code when parsing JSON and validating URLs.

Performance Example

import json
import timeit
from urllib.parse import urlparse

import requests

from pydantic import HttpUrl, TypeAdapter

reps = 7
number = 100
r = requests.get('https://api.github.com/emojis')
r.raise_for_status()
emojis_json = r.content


def emojis_pure_python(raw_data):
    data = json.loads(raw_data)
    output = {}
    for key, value in data.items():
        assert isinstance(key, str)
        url = urlparse(value)
        assert url.scheme in ('https', 'http')
        output[key] = url


emojis_pure_python_times = timeit.repeat(
    'emojis_pure_python(emojis_json)',
    globals={
        'emojis_pure_python': emojis_pure_python,
        'emojis_json': emojis_json,
    },
    repeat=reps,
    number=number,
)
print(f'pure python: {min(emojis_pure_python_times) / number * 1000:0.2f}ms')
# > pure python: 5.32ms

type_adapter = TypeAdapter(dict[str, HttpUrl])
emojis_pydantic_times = timeit.repeat(
    'type_adapter.validate_json(emojis_json)',
    globals={
        'type_adapter': type_adapter,
        'HttpUrl': HttpUrl,
        'emojis_json': emojis_json,
    },
    repeat=reps,
    number=number,
)
print(f'pydantic: {min(emojis_pydantic_times) / number * 1000:0.2f}ms')
# > pydantic: 1.54ms

print(
    f'Pydantic {min(emojis_pure_python_times) / min(emojis_pydantic_times):0.2f}x faster'
)
# > Pydantic 3.45x faster

MkDocstrings⚓︎

Sunsetting Gitter and Related Links⚓︎

Features⚓︎

Used By⚓︎

Installation⚓︎

Quick Usage⚓︎

Sponsors⚓︎

MkDocstrings ⚓︎