mkdocstrings

Language Handlers

mkdocstrings is language-agnostic. It relies on handlers to bridge the gap between source code and documentation. Each handler is responsible for collecting and rendering documentation for a specific language (e.g., Python, TypeScript, C).

Inline Injection

Instead of generating separate Markdown files, mkdocstrings uses an injection model. You place an identifier in your existing Markdown content using the ::: identifier syntax. The identifier and any accompanying YAML configuration are passed to the appropriate handler to render the documentation directly into your page.

Cross-references

• Across pages: You can reference any heading produced by a handler using Markdown link syntax like [identifier][] or [title][identifier].
• Across sites: Similar to Sphinx's intersphinx, mkdocstrings can reference API items from other projects if they provide an inventory that you load in your configuration.

When generating documentation pages automatically, you must also automate the MkDocs navigation (nav). By combining mkdocs-gen-files with mkdocs-literate-nav, you can build a navigation tree programmatically in a Python script and output it to a SUMMARY.md file.

Setup

1. Add mkdocs-literate-nav to your dependencies.
2. Configure mkdocs.yml to use the plugin and point to your generated summary:

plugins:
- search
- gen-files:
    scripts:
    - scripts/gen_ref_pages.py
- literate-nav:
    nav_file: SUMMARY.md
- mkdocstrings

3. In your mkdocs.yml navigation, defer the code reference section to the generated folder:

nav:
- Code Reference: reference/

(Note: The trailing slash is required so mkdocs-literate-nav looks for SUMMARY.md inside that directory.)

Implementation Example

Update your generation script to use mkdocs_gen_files.Nav() to build the tree and write the SUMMARY.md at the end.

import mkdocs_gen_files
from pathlib import Path

nav = mkdocs_gen_files.Nav()
root = Path(__file__).parent.parent
src = root / "src"

for path in sorted(src.rglob("*.py")):
    module_path = path.relative_to(src).with_suffix("")
    doc_path = path.relative_to(src).with_suffix(".md")
    full_doc_path = Path("reference", doc_path)

    parts = tuple(module_path.parts)
    if parts[-1] == "__init__":
        parts = parts[:-1]
    elif parts[-1] == "__main__":
        continue

    nav[parts] = doc_path.as_posix()

    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
        ident = ".".join(parts)
        fd.write(f"::: {ident}")

    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))

# Write the literate navigation file
with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
    nav_file.writelines(nav.build_literate_nav())

To prevent __init__ modules from appearing as expandable/collapsible items in your navigation (which can clutter the API view), you can use mkdocs-section-index. This plugin allows you to bind the documentation of an __init__ module directly to its parent section/folder.

Setup

1. Add mkdocs-section-index to your dependencies.
2. Add it to your mkdocs.yml plugins list:

plugins:
- search
- gen-files:
    scripts:
    - scripts/gen_ref_pages.py
- literate-nav:
    nav_file: SUMMARY.md
- section-index
- mkdocstrings

Implementation

In your generation script, when an __init__ module is encountered, rename its target documentation path to index.md. This tells the plugin to treat the module's content as the index for that directory/section.

# Inside your generation loop
if parts[-1] == "__init__":
    parts = parts[:-1]
    doc_path = doc_path.with_name("index.md")
    full_doc_path = full_doc_path.with_name("index.md")
# ... proceed to write the file ...

Developers can extend or alter the behavior of existing handlers (e.g., the Python handler) by creating third-party packages that register additional template folders. This is primarily used to add specific support for other libraries within a handler.

An extension is a Python package that defines a specific entry-point in its pyproject.toml. The entry-point must provide a get_templates_path function that returns a pathlib.Path or str pointing to a directory containing templates.

Template Directory Structure: The directory must contain one subfolder for each supported theme (e.g., material, mkdocs, readthedocs). The extension is responsible for ensuring the handler uses these templates by mutating collected data, as per the specific handler's extension support documentation.

[project.entry-points."mkdocstrings.python.templates"]
extension-name = "extension_package:get_templates_path"

from pathlib import Path


def get_templates_path() -> Path:
    return Path(__file__).parent / "templates"