mkdocstrings

mkdocstrings is a MkDocs plugin that inserts automatically generated API documentation into your documentation pages. You reference an object with a simple identifier syntax inside your Markdown, and mkdocstrings collects its signature, docstring, and structure from the source, then renders it inline alongside your hand-written prose.

It is language-agnostic through a system of pluggable handlers, with first-class support for Python (backed by Griffe) and community handlers for other languages such as Crystal. Cross-references, an inventory for linking between projects, and theming let generated reference docs blend seamlessly into a MkDocs site.

What You Get

• Automatic API documentation injected into Markdown pages from an object identifier
• A pluggable handler system with official Python support (via Griffe) and community handlers for other languages
• Automatic cross-references between documented objects and an inventory for inter-project linking
• Deep integration with the MkDocs build lifecycle and Material for MkDocs theming
• Configurable rendering options controlling headings, members, signatures, and docstring styles

Common Use Cases

• Generating a complete API reference for a Python library without maintaining it by hand
• Mixing narrative guides with auto-generated reference documentation on the same page
• Linking documentation across multiple projects using downloadable inventories

Under The Hood

Architecture - mkdocstrings registers as a MkDocs plugin (src/mkdocstrings/_internal/plugin.py) and a Markdown extension (extension.py) that scans pages for autodoc identifiers. When it finds one, it dispatches to a language handler under _internal/handlers, which collects the object’s structure (for Python, via the Griffe library) and renders it through Jinja2 templates. An inventory module builds and consumes objects.inv-style inventories for cross-project references, autorefs resolves links between rendered objects, and download.py fetches remote inventories. The plugin hooks the MkDocs build lifecycle so generated reference blends into the rest of the site.

Tech Stack - Pure Python built on Jinja2 (templating), Markdown and PyMdown Extensions (parsing), MarkupSafe, and mkdocs plus mkdocs-autorefs. Language support is delivered via separately-installed handler packages (mkdocstrings-python, mkdocstrings-crystal), declared as optional extras. Packaging is PEP 621 with a src/ layout and a py.typed marker.

Code Quality - The repository ships a focused pytest suite (test_plugin, test_handlers, test_extension, test_inventory, test_api, test_download, test_loggers) with fixtures, and the code is organized behind an _internal package to keep the public API surface deliberate. Type hints and a py.typed marker indicate a typed, maintained codebase.

API Design - For end users the interface is almost entirely declarative: enable the plugin in mkdocs.yml, set handler options, and write identifier references in Markdown. For handler authors, mkdocstrings exposes a clear extension contract (collect/render) so new languages plug in without touching the core, which keeps day-to-day usage nearly config-only.