mkdocstrings

Automatic documentation from sources, for MkDocs.
Come have a chat or ask questions on our Gitter channel.

---

Features - Installation - Quick usage

Features

• Language-agnostic:
  just like MkDocs, mkdocstrings is written in Python but is language-agnostic.
  It means you can use it with any programming language, as long as there is a
  handler for it.
  We currently have handlers for the
  C,
  Crystal,
  Python,
  TypeScript, and
  VBA languages,
  as well as for shell scripts/libraries.
  Maybe you’d like to add another one to the list? 😉

• Multiple themes support:
  each handler can offer multiple themes. Currently, we offer the
  ⭐ Material theme ⭐
  as well as basic support for the ReadTheDocs and MkDocs themes for the Python handler.

• Cross-references across pages:
  mkdocstrings makes it possible to reference headings in other Markdown files with the classic Markdown linking
  syntax: [identifier][] or [title][identifier] – and you don’t need to remember which exact page this object was
  on. This works for any heading that’s produced by a mkdocstrings language handler, and you can opt to include
  any Markdown heading into the global referencing scheme.

  Note: in versions prior to 0.15 all Markdown headers were included, but now you need to
  opt in.

• Cross-references across sites:
  similarly to Sphinx’s intersphinx extension,
  mkdocstrings can reference API items from other libraries, given they provide an inventory and you load
  that inventory in your MkDocs configuration.

• Inline injection in Markdown:
  instead of generating Markdown files, mkdocstrings allows you to inject
  documentation anywhere in your Markdown contents. The syntax is simple: ::: identifier followed by a 4-spaces
  indented YAML block. The identifier and YAML configuration will be passed to the appropriate handler
  to collect and render documentation.

• Global and local configuration:
  each handler can be configured globally in mkdocs.yml, and locally for each
  “autodoc” instruction.

• Reasonable defaults:
  you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.

Used by

mkdocstrings is used by well-known companies, projects and scientific teams:
Ansible,
Apache,
FastAPI,
Google,
Jitsi,
Microsoft,
Prefect,
Pydantic,
and more…

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.

---

With conda:

conda install -c conda-forge mkdocstrings mkdocstrings-python

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!