MkDocs Monorepo Plugin

1.1.2 · active · verified Fri Apr 10

The mkdocs-monorepo-plugin provides monorepository support for MkDocs, allowing users to build multiple sets of documentation from a single MkDocs site. It addresses challenges in large codebases by enabling individual teams to manage their documentation (including `mkdocs.yml` files and `docs/` folders) within subdirectories, which are then intelligently merged into a single, cohesive documentation site. The current version is 1.1.2 and it follows a release cadence driven by new features, bug fixes, and compatibility updates.

Warnings

gotcha The mkdocs-monorepo-plugin is currently in beta. While stability is generally good, it may not be fully compatible with all advanced MkDocs configurations or other plugins, potentially leading to unexpected behavior.
Fix: Review the plugin's GitHub issues and official documentation for known incompatibilities. Test thoroughly with your specific MkDocs setup and other plugins.
breaking Python 3.7 support was officially dropped in version 1.1.0, and Python 3.8 support was dropped in 1.1.2. Users on these older Python versions must upgrade to Python 3.9 or later.
Fix: Upgrade your Python environment to version 3.9, 3.10, 3.11, or 3.12.
gotcha Compatibility issues have been reported when using `mkdocs-monorepo-plugin` in conjunction with `mkdocstrings`, particularly when sub-projects have conflicting Python dependency requirements or when `mkdocstrings` cannot locate modules.
Fix: Ensure that all required Python packages for code references are installed in the environment where `mkdocs build` is run. For `mkdocstrings`, verify `paths` configuration in all `mkdocs.yml` files. Refer to related GitHub issues on both plugin repositories for advanced workarounds or configurations.
breaking Version 1.1.1 removed the use of `warning_filter` to align with its deprecation in MkDocs 1.2. Custom configurations relying on `warning_filter` might need adjustment if using older plugin versions with newer MkDocs.
Fix: Upgrade to mkdocs-monorepo-plugin version 1.1.1 or later. If on an older version, ensure your MkDocs setup does not explicitly rely on `warning_filter` in a way that conflicts with MkDocs 1.2+.
gotcha Prior to version 1.0.4, the plugin had a bug preventing it from working correctly with MkDocs versions 1.4.0 and newer. Ensure you are using at least version 1.0.4 of the `mkdocs-monorepo-plugin` for compatibility with recent MkDocs releases.
Fix: Upgrade `mkdocs-monorepo-plugin` to version 1.0.4 or higher to ensure compatibility with MkDocs >= 1.4.0.

Install

pip install mkdocs-monorepo-plugin Install with pip

Imports

monorepo plugin
```
plugins:
  - monorepo
```
The mkdocs-monorepo-plugin is configured directly in your mkdocs.yml file, not imported as a Python module in user code. Add 'monorepo' to the 'plugins' section of your root mkdocs.yml to enable it.

Quickstart

This quickstart creates a simple monorepo documentation structure. A root `mkdocs.yml` includes sub-project `mkdocs.yml` files using the `!include` syntax. Run `mkdocs serve` from the root directory to build and view the merged documentation.

mkdir my-monorepo-docs
cd my-monorepo-docs

# Root mkdocs.yml
cat <<EOF > mkdocs.yml
site_name: My Monorepo Documentation
nav:
  - Home: 'index.md'
  - API v1: '!include api/v1/mkdocs.yml'
  - API v2: '!include api/v2/mkdocs.yml'
plugins:
  - monorepo
EOF

# Root index.md
cat <<EOF > index.md
# Welcome to My Monorepo Docs!

This is the main documentation site.
EOF

mkdir api
mkdir api/v1
mkdir api/v2

# Sub-project 1: api/v1
cat <<EOF > api/v1/mkdocs.yml
site_name: API v1 Docs
nav:
  - Overview: 'index.md'
  - Endpoints: 'endpoints.md'
EOF

cat <<EOF > api/v1/index.md
# API Version 1 Overview

Details for the first version of our API.
EOF

cat <<EOF > api/v1/endpoints.md
# API v1 Endpoints

- `/users`
- `/products`
EOF

# Sub-project 2: api/v2
cat <<EOF > api/v2/mkdocs.yml
site_name: API v2 Docs
nav:
  - New Features: 'index.md'
  - Migration Guide: 'migration.md'
EOF

cat <<EOF > api/v2/index.md
# API Version 2: What's New

Introducing the second iteration of our API.
EOF

cat <<EOF > api/v2/migration.md
# Migrating to API v2

Follow these steps to upgrade.
EOF

# Build and serve the documentation
mkdocs serve

view raw JSON →