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.
pip install mkdocs-monorepo-pluginVerified import paths — ran on the pinned version, not inferred.
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.
Review the plugin's GitHub issues and official documentation for known incompatibilities. Test thoroughly with your specific MkDocs setup and other plugins.
Upgrade your Python environment to version 3.9, 3.10, 3.11, or 3.12.
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.
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+.
Upgrade `mkdocs-monorepo-plugin` to version 1.0.4 or higher to ensure compatibility with MkDocs >= 1.4.0.