{"id":14065054,"url":"https://github.com/backstage/mkdocs-monorepo-plugin","last_synced_at":"2025-04-12T20:36:23.298Z","repository":{"id":39997856,"uuid":"209620952","full_name":"backstage/mkdocs-monorepo-plugin","owner":"backstage","description":"✚ Build multiple documentation folders in a single Mkdocs. Designed for large codebases.","archived":false,"fork":false,"pushed_at":"2025-01-30T19:03:52.000Z","size":3462,"stargazers_count":343,"open_issues_count":43,"forks_count":74,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-05T19:03:15.820Z","etag":null,"topics":["documentation","mkdocs","mkdocs-monorepo-plugin","monoliths","monorepos","plugin"],"latest_commit_sha":null,"homepage":"https://backstage.github.io/mkdocs-monorepo-plugin/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/backstage.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-19T18:18:32.000Z","updated_at":"2025-04-04T05:31:52.000Z","dependencies_parsed_at":"2024-01-03T16:40:58.269Z","dependency_job_id":"588561ce-f133-4a0e-9cf3-264b6005a048","html_url":"https://github.com/backstage/mkdocs-monorepo-plugin","commit_stats":{"total_commits":98,"total_committers":26,"mean_commits":3.769230769230769,"dds":0.8877551020408163,"last_synced_commit":"15f39102d039d1ec4a074d120bb1a0e96614993d"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backstage%2Fmkdocs-monorepo-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backstage%2Fmkdocs-monorepo-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backstage%2Fmkdocs-monorepo-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/backstage%2Fmkdocs-monorepo-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/backstage","download_url":"https://codeload.github.com/backstage/mkdocs-monorepo-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631225,"owners_count":21136550,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","mkdocs","mkdocs-monorepo-plugin","monoliths","monorepos","plugin"],"created_at":"2024-08-13T07:04:15.817Z","updated_at":"2025-04-12T20:36:23.273Z","avatar_url":"https://github.com/backstage.png","language":"Python","readme":"# backstage/mkdocs-monorepo-plugin\n\n[![](https://github.com/backstage/mkdocs-monorepo-plugin/workflows/Build%2C%20Test%20%26%20Deploy/badge.svg)](https://github.com/backstage/mkdocs-monorepo-plugin/actions)\n[![PyPI](https://img.shields.io/pypi/v/mkdocs-monorepo-plugin)](https://pypi.org/project/mkdocs-monorepo-plugin/)\n![](https://img.shields.io/badge/lifecycle-stable-509bf5.svg)\n[![PyPI - License](https://img.shields.io/pypi/l/mkdocs-monorepo-plugin)](LICENSE)\n\n✚ This plugin enables you to build multiple sets of documentation in a single Mkdocs. It is designed to address writing documentation in Spotify's largest and most business-critical codebases (typically monoliths or monorepos).\n\n✏️ [Blog Post](https://labs.spotify.com/2019/10/01/solving-documentation-for-monoliths-and-monorepos/) | 🐍 [Python Package](https://pypi.org/project/mkdocs-monorepo-plugin/) | ✚ [Demo](https://backstage.github.io/mkdocs-monorepo-plugin/monorepo-example/) | 📕 [Docs](https://backstage.github.io/mkdocs-monorepo-plugin/)\n\n## Features\n\n- **Support for multiple `docs/` folders in Mkdocs.** Having a single `docs/` folder in a large codebase is hard to maintain. Who owns which documentation? What code is it associated with? Bringing docs closer to the associated code enables you to update them better, as well as leverage folder-based features such as [GitHub Codeowners].\n\n- **Support for multiple navigations.** In Spotify, large repositories typically are split up by multiple owners. These are split by folders. By introducing multiple `mkdocs.yml` files along with multiple `docs/` folder, each team can take ownership of their own navigation. This plugin then intelligently merges of the documentation together into a single repository.\n\n- **Support across multiple repositories.** Using [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) it is possible to merge documentation across multiple repositories into a single codebase dynamically.\n\n- **The same great Mkdocs developer experience.** It is possible to run `mkdocs serve` in the root to merge all of your documentation together, or in a subfolder to build specific documentation. Autoreload still works as usual. No more using [symlinks](https://devdojo.com/tutorials/what-is-a-symlink)!\n\n## Install\n\nIt's easy to get started using [PyPI] and `pip` using Python:\n\n```terminal\n$ pip install mkdocs-monorepo-plugin\n```\n\n## Usage\n\nTake a look in [our sample project](./sample-docs) for an example implementation, or see [what it looks like after running `mkdocs build`](https://backstage.github.io/mkdocs-monorepo-plugin/monorepo-example/).\n\nIn general, this plugin introduces the `!include` syntax in your Mkdocs navigation structure and then merges them together.\n\n```yaml\n# /mkdocs.yml\nsite_name: Cats API\n\nnav:\n  - Intro: 'index.md'\n  - Authentication: 'authentication.md'\n  - API:\n    - v1: '!include ./v1/mkdocs.yml'\n    - v2: '!include ./v2/mkdocs.yml'\n\nplugins:\n  - monorepo\n\n```\n```yaml\n# /src/v1/mkdocs.yml\nsite_name: versions/v1\n\nnav:\n  - Reference: \"reference.md\"\n  - Changelog: \"changelog.md\"\n\n```\n```yaml\n# /src/v2/mkdocs.yml\nsite_name: versions/v2\n\nnav:\n  - Migrating to v2: \"migrating.md\"\n  - Reference: \"reference.md\"\n  - Changelog: \"changelog.md\"\n\n```\n\n#### Example Source Filetree\n\n```terminal\n$ tree .\n\n├── docs\n│   ├── authentication.md\n│   └── index.md\n├── mkdocs.yml\n├── v1\n│   ├── docs\n│   │   ├── changelog.md\n│   │   └── reference.md\n│   └── mkdocs.yml\n└── v2\n    ├── docs\n    │   ├── changelog.md\n    │   ├── migrating.md\n    │   └── reference.md\n    └── mkdocs.yml\n\n5 directories, 10 files\n```\n\n#### Example Rendered Filetree\n\n```\n$ mkdocs build\n$ tree ./site\n\n├── 404.html\n├── authentication\n│   └── index.html\n├── css\n│   ├── base.css\n│   ├── bootstrap-custom.min.css\n│   └── font-awesome.min.css\n├── fonts\n│   ├── fontawesome-webfont.eot\n│   ├── fontawesome-webfont.svg\n│   ├── fontawesome-webfont.ttf\n│   ├── fontawesome-webfont.woff\n│   ├── fontawesome-webfont.woff2\n│   ├── glyphicons-halflings-regular.eot\n│   ├── glyphicons-halflings-regular.svg\n│   ├── glyphicons-halflings-regular.ttf\n│   ├── glyphicons-halflings-regular.woff\n│   └── glyphicons-halflings-regular.woff2\n├── img\n│   ├── favicon.ico\n│   └── grid.png\n├── index.html\n├── js\n│   ├── base.js\n│   ├── bootstrap-3.0.3.min.js\n│   └── jquery-1.10.2.min.js\n├── sitemap.xml\n├── sitemap.xml.gz\n└── versions\n    ├── v1\n    │   ├── changelog\n    │   │   └── index.html\n    │   └── reference\n    │       └── index.html\n    └── v2\n        ├── changelog\n        │   └── index.html\n        ├── migrating\n        │   └── index.html\n        └── reference\n            └── index.html\n\n13 directories, 28 files\n```\n\nNote that, as of `v0.5.2`, the `*include` syntax can be used in place of `!include` in order to compile any number of `mkdocs.yml` files that match a glob-like pattern, without having to specify every one individually. For example:\n\n\n```yaml\n# /mkdocs.yml\nsite_name: Cats System\n\nnav:\n  - Intro: 'index.md'\n  - Components: '*include ./components/*/mkdocs.yml'\n```\n\n#### Example Source Filetree\n\n```terminal\n$ tree .\n\n├── components\n│   ├── belly-rubs\n│   │   ├── docs\n│   │   |   └── index.md\n│   │   └── mkdocs.yml\n|   ├── purring\n│   │   ├── docs\n│   │   |   └── index.md\n│   │   └── mkdocs.yml\n|   └── skritches\n│   │   ├── docs\n│   │   |   └── index.md\n│   │   └── mkdocs.yml\n├── docs\n│   └── index.md\n└── mkdocs.yml\n\n8 directories, 8 files\n```\n\n### Release\n\n1. Update the [CHANGELOG.md](./docs/CHANGELOG.md).\n2. Bump up the version number in `setup.py` which triggers the release workflow on [GitHub Actions](.github/workflows/deploy.yml) to publish a new version in PyPI.\n\n## Supported Versions\n\n- Python 3.8, 3.9, 3.10, 3.11, 3.12\n- [Mkdocs] 1.0.4 and above.\n\n## Changelog\n\nCheck out our [CHANGELOG.md](./docs/CHANGELOG.md) for details.\n\n## License\n\nCopyright 2020-2021 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage\n\nLicensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0\n\n## Contributing\n\nCheck out our [CONTRIBUTING](./docs/CONTRIBUTING.md) for more details.\n\n[mkdocs/mkdocs]: https://github.com/mkdocs/mkdocs\n[mkdocs-plugin-template]: https://github.com/byrnereese/mkdocs-plugin-template\n[pypi]: https://pypi.org\n[mkdocs]: https://www.mkdocs.org\n[github codeowners]: https://help.github.com/en/articles/about-code-owners\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackstage%2Fmkdocs-monorepo-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbackstage%2Fmkdocs-monorepo-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbackstage%2Fmkdocs-monorepo-plugin/lists"}