mkdocstrings-multirepo

A simple mkdocs + mkdocstrings plugin that allows you to use docs from multiple different repos. Simply specify a repo configuration, and those repos become available to mkdocstrings in one docs build.

Installation

uv add mkdocstrings-multirepo

Requirements: Requires git, mkdocs and mkdocstrings to be installed and configured.

[!IMPORTANT]

mkdocstrings-multirepo must be listed before mkdocstrings in your plugins configuration, as it needs to set up repository paths before mkdocstrings processes them.

Features

• Lean & parallel cloning - Only fetches the specified ref, and fetches multiple repos concurrently for faster builds
• Reproducibility - Supports and encourages the use of commit hashes to pin specific repo versions
• Caching - Repos are cached in your OS cache directory (e.g. ~/.cache/mkdocstrings-multirepo on Linux) and reused between builds
• Auto-pruning - Automatically removes unused cached repos when the cache grows too large

Example

# mkdocs.yml

site_name: mkdocstrings-multirepo

plugins:
  - mkdocstrings-multirepo:
      repos:
        - name: textual
          url: "https://github.com/Textualize/textual.git"
          ref: "501372027f3abc75561881e3803efc34098dabe1"
        - name: rich
          url: "https://github.com/Textualize/rich.git"
          ref: "1d402e0c59f8765e420a5a4440eb2fca7465d1ae"
        - name: pydantic
          url: "https://github.com/pydantic/pydantic.git"
          ref: "08b64f7a43f96f02bb0af8d46aba67b3a68d6e88"
  - mkdocstrings:

<!-- A .md file in your docs -->

# Example

<!-- Schema: `::: [name-in-repos-config].path.to.your.module` -->

::: textual.src.textual.cache.LRUCache

::: rich.rich.console.ConsoleDimensions

::: pydantic.pydantic.networks.UrlConstraints

Limitations

• Language support - mkdocstrings-multirepo currently only supports the Python parser. Making this language agnostic seems quite simple, so full language support may come in the v0.2 release.

FAQ

Why does mkdocstrings-multirepo notably increase my build times, even when repos are cached?

Including and referencing modules from other repos inherently increases the strain on mkdocstrings. Large repos with deeply nested references may require griffe (the mkdocstrings parser) to recurse a large number of times.

Why am I getting "Could not collect" errors when trying to document a cloned repo?

This could be for a variety of reasons, such as not using the correct naming scheme, misspelling a path, etc.

One dubious edge case to be aware of is: if you have a package installed in your environment (e.g., the mkdocstrings_multirepo package itself) and you're also trying to clone and document a repo with the same name in your config, you'll encounter name collision issues.

You can solve this by either:

1. Removing the repo from your config, and documenting the package directly. mkdocstrings directly supports documenting packages installed in your environment. (Recommended)

2. If you really need the package in your repos configuration, change the name such that it doesn't conflict with the name of any installed packages. For example, to clone and document mkdocstrings-multirepo when you also have mkdocstrings-multirepo installed, you could do:

plugins:
  - mkdocstrings-multirepo:
      repos:
        - name: mkdocstrings_multirepo_repo # Changed to avoid collision
          url: "https://github.com/kay-mw/mkdocstrings-multirepo.git"
          ref: "main"

Then reference it as ::: mkdocstrings_multirepo_repo.path.to.some.module.

Does this plugin work with zensical?

Unfortunately not, as this plugin uses the mkdocs plugin API. Zensical doesn't appear to have a public plugin/module API yet, however I plan to port this plugin to zensical as soon as that becomes possible.