mkdocs-multirepo-plugin

0.8.3 verified Fri May 01 auth: no python

MkDocs plugin to build documentation from multiple repositories into one unified site. Version 0.8.3. Release cadence: irregular, several releases per year.

pip install mkdocs-multirepo-plugin

Common errors

error Error: The plugin 'multirepo' does not exist ↓

cause The plugin is not installed or configuration uses wrong name.

fix

Install with pip install mkdocs-multirepo-plugin and ensure configuration uses - multirepo (not - mkdocs-multirepo-plugin).

error fatal: destination path '<path>' already exists and is not an empty directory. ↓

cause The cloned repo directory already exists from a previous build. The plugin does not clean it automatically.

fix

Delete the cloned directory manually or use a CI clean step: rm -rf <path> before building docs.

error No module named 'mkdocs_multirepo_plugin' ↓

cause Import error when trying to use plugin in Python code (e.g., for custom hooks).

fix

The correct import path is from mkdocs_multirepo_plugin.plugin import MultiRepoPlugin. However, the plugin should be used via mkdocs.yml, not imported directly.

Warnings

gotcha The plugin requires the Git executable to be installed and available in PATH. Cloning repos fails silently if git is missing. ↓

fix Ensure git is installed: `git --version` should succeed.

deprecated The `repos` configuration parameter was deprecated in favour of `nav_repos` for navigation support. Using `repos` without a nav may yield unexpected navigation ordering. ↓

fix Use `nav_repos` with a `nav` key to control navigation structure.

gotcha When using `!import` statements in mkdocs.yml, the path must be relative to the docs directory. Relative paths from project root cause import errors. ↓

fix Use relative paths starting from the docs directory, e.g., `!import path/to/file.md`.

breaking In version 0.6.0, the default behaviour changed: docs_dir contents are moved into a subdirectory. Set `keep_docs_dir: true` to preserve existing behaviour. ↓

fix Add `keep_docs_dir: true` to the plugin config if you want the docs_dir to remain unchanged.

Imports

plugin
wrong
```
plugins:
  - mkdocs-multirepo-plugin
```
correct
```
plugins:
  - multirepo
```
The plugin is registered by its short name 'multirepo', not the full package name.

Quickstart

Basic configuration to include documentation from an external git repository.

# mkdocs.yml
site_name: My Docs
plugins:
  - multirepo:
      repos:
        - section: Repo A
          url: https://github.com/example/repo-a.git
          branch: main