{"id":2589,"library":"mkdocs-monorepo-plugin","title":"MkDocs Monorepo Plugin","description":"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.","status":"active","version":"1.1.2","language":"en","source_language":"en","source_url":"https://github.com/backstage/mkdocs-monorepo-plugin","tags":["mkdocs","monorepo","documentation","plugin"],"install":[{"cmd":"pip install mkdocs-monorepo-plugin","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This is an MkDocs plugin and requires MkDocs to function.","package":"mkdocs","optional":false}],"imports":[{"note":"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.","symbol":"monorepo plugin","correct":"plugins:\n  - monorepo"}],"quickstart":{"code":"mkdir my-monorepo-docs\ncd my-monorepo-docs\n\n# Root mkdocs.yml\ncat <<EOF > mkdocs.yml\nsite_name: My Monorepo Documentation\nnav:\n  - Home: 'index.md'\n  - API v1: '!include api/v1/mkdocs.yml'\n  - API v2: '!include api/v2/mkdocs.yml'\nplugins:\n  - monorepo\nEOF\n\n# Root index.md\ncat <<EOF > index.md\n# Welcome to My Monorepo Docs!\n\nThis is the main documentation site.\nEOF\n\nmkdir api\nmkdir api/v1\nmkdir api/v2\n\n# Sub-project 1: api/v1\ncat <<EOF > api/v1/mkdocs.yml\nsite_name: API v1 Docs\nnav:\n  - Overview: 'index.md'\n  - Endpoints: 'endpoints.md'\nEOF\n\ncat <<EOF > api/v1/index.md\n# API Version 1 Overview\n\nDetails for the first version of our API.\nEOF\n\ncat <<EOF > api/v1/endpoints.md\n# API v1 Endpoints\n\n- `/users`\n- `/products`\nEOF\n\n# Sub-project 2: api/v2\ncat <<EOF > api/v2/mkdocs.yml\nsite_name: API v2 Docs\nnav:\n  - New Features: 'index.md'\n  - Migration Guide: 'migration.md'\nEOF\n\ncat <<EOF > api/v2/index.md\n# API Version 2: What's New\n\nIntroducing the second iteration of our API.\nEOF\n\ncat <<EOF > api/v2/migration.md\n# Migrating to API v2\n\nFollow these steps to upgrade.\nEOF\n\n# Build and serve the documentation\nmkdocs serve","lang":"bash","description":"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."},"warnings":[{"fix":"Review the plugin's GitHub issues and official documentation for known incompatibilities. Test thoroughly with your specific MkDocs setup and other plugins.","message":"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.","severity":"gotcha","affected_versions":"All beta versions (up to 1.1.2)"},{"fix":"Upgrade your Python environment to version 3.9, 3.10, 3.11, or 3.12.","message":"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.","severity":"breaking","affected_versions":">=1.1.0 (for Python 3.7), >=1.1.2 (for Python 3.8)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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+.","message":"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.","severity":"breaking","affected_versions":"<1.1.1"},{"fix":"Upgrade `mkdocs-monorepo-plugin` to version 1.0.4 or higher to ensure compatibility with MkDocs >= 1.4.0.","message":"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.","severity":"gotcha","affected_versions":"<1.0.4"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}