β 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).
βοΈ Blog Post | π Python Package | β Demo | π Docs
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.
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.
Support across multiple repositories. Using Git Submodules it is possible to merge documentation across multiple repositories into a single codebase dynamically.
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!
It's easy to get started using PyPI and pip
using Python:
$ pip install mkdocs-monorepo-plugin
Take a look in our sample project for an example implementation, or see what it looks like after running mkdocs build
.
In general, this plugin introduces the !include
syntax in your Mkdocs navigation structure and then merges them together.
# /mkdocs.yml
site_name: Cats API
nav:
- Intro: 'index.md'
- Authentication: 'authentication.md'
- API:
- v1: '!include ./v1/mkdocs.yml'
- v2: '!include ./v2/mkdocs.yml'
plugins:
- monorepo
# /src/v1/mkdocs.yml
site_name: versions/v1
nav:
- Reference: "reference.md"
- Changelog: "changelog.md"
# /src/v2/mkdocs.yml
site_name: versions/v2
nav:
- Migrating to v2: "migrating.md"
- Reference: "reference.md"
- Changelog: "changelog.md"
$ tree .
βββ docs
βΒ Β βββ authentication.md
βΒ Β βββ index.md
βββ mkdocs.yml
βββ v1
βΒ Β βββ docs
βΒ Β βΒ Β βββ changelog.md
βΒ Β βΒ Β βββ reference.md
βΒ Β βββ mkdocs.yml
βββ v2
βββ docs
βΒ Β βββ changelog.md
βΒ Β βββ migrating.md
βΒ Β βββ reference.md
βββ mkdocs.yml
5 directories, 10 files
$ mkdocs build
$ tree ./site
βββ 404.html
βββ authentication
βΒ Β βββ index.html
βββ css
βΒ Β βββ base.css
βΒ Β βββ bootstrap-custom.min.css
βΒ Β βββ font-awesome.min.css
βββ fonts
βΒ Β βββ fontawesome-webfont.eot
βΒ Β βββ fontawesome-webfont.svg
βΒ Β βββ fontawesome-webfont.ttf
βΒ Β βββ fontawesome-webfont.woff
βΒ Β βββ fontawesome-webfont.woff2
βΒ Β βββ glyphicons-halflings-regular.eot
βΒ Β βββ glyphicons-halflings-regular.svg
βΒ Β βββ glyphicons-halflings-regular.ttf
βΒ Β βββ glyphicons-halflings-regular.woff
βΒ Β βββ glyphicons-halflings-regular.woff2
βββ img
βΒ Β βββ favicon.ico
βΒ Β βββ grid.png
βββ index.html
βββ js
βΒ Β βββ base.js
βΒ Β βββ bootstrap-3.0.3.min.js
βΒ Β βββ jquery-1.10.2.min.js
βββ sitemap.xml
βββ sitemap.xml.gz
βββ versions
βββ v1
βΒ Β βββ changelog
βΒ Β βΒ Β βββ index.html
βΒ Β βββ reference
βΒ Β βββ index.html
βββ v2
βββ changelog
βΒ Β βββ index.html
βββ migrating
βΒ Β βββ index.html
βββ reference
βββ index.html
13 directories, 28 files
Note 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:
# /mkdocs.yml
site_name: Cats System
nav:
- Intro: 'index.md'
- Components: '*include ./components/*/mkdocs.yml'
$ tree .
βββ components
βΒ Β βββ belly-rubs
βΒ Β βΒ Β βββ docs
β β | βββ index.md
βΒ Β βΒ Β βββ mkdocs.yml
| βββ purring
βΒ Β βΒ Β βββ docs
β β | βββ index.md
βΒ Β βΒ Β βββ mkdocs.yml
| βββ skritches
βΒ Β βΒ Β βββ docs
β β | βββ index.md
βΒ Β βΒ Β βββ mkdocs.yml
βββ docs
βΒ Β βββ index.md
βββ mkdocs.yml
8 directories, 8 files
setup.py
which triggers the release workflow on GitHub Actions to publish a new version in PyPI.Check out our CHANGELOG.md for details.
Copyright 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
Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
Check out our CONTRIBUTING for more details.