DOCSEARCHbyAlgolia
Submit Docs

mkdocs-monorepo-plugin

repository·master·Indexed 18 days ago

https://github.com/backstage/mkdocs-monorepo-plugin

A MkDocs plugin for large-scale repositories (monoliths/monorepos) that merges multiple documentation sets, navigation structures, and 'docs/' directories into a single unified site. It supports multiple mkdocs.yml files via !include and *include (glob patterns) syntax, allowing teams to maintain documentation closer to their specific code. Compatible with Python 3.9-3.12 and MkDocs 1.0.4+.

Tokens
3.1K
Snippets
17
Records
29
Agent score
59%

What's inside mkdocs-monorepo-plugin

  1. Understand the core concept of the mkdocs-monorepo-plugin

    master

    The mkdocs-monorepo-plugin is designed for large codebases (monorepos or monoliths) where documentation ownership is complex. Instead of maintaining one massive, centralized documentation repository, this plugin allows you to split documentation into smaller, localized folders distributed throughout your codebase.

    Key Workflow:

    1. Decentralized Documentation: Documentation lives alongside the code in smaller, manageable folders.
    2. Ownership Alignment: By localizing docs to specific directories, you can leverage existing code ownership strategies, such as GitHub Codeowners, to manage who can change specific parts of the documentation.
    3. Unified Build: When shipping to production, the plugin merges these distributed documentation pieces into a single, cohesive MkDocs site.

  3. How the monorepo plugin works

    master

    The mkdocs-monorepo-plugin allows you to manage documentation for large codebases (monoliths or monorepos) by enabling:

    • Multiple docs/ folders: Instead of one central docs/ directory, different teams can maintain documentation closer to their specific code.
    • Multiple navigations: Each sub-module can have its own mkdocs.yml file to define its own navigation structure.
    • Cross-repository support: You can use Git Submodules to merge documentation from different repositories into a single MkDocs build.
    • Intelligent Merging: The plugin merges these disparate configurations into a single, unified documentation site.

    It uses a special !include (or *include for glob patterns) syntax within the main nav section of your root mkdocs.yml to pull in sub-configurations.

  4. How the monorepo plugin works: Navigation and Merging

    master

    The plugin operates in two distinct phases to enable a monorepo documentation structure:

    1. Resolving the navigation

    When the plugin encounters a !include statement within the nav section of the root mkdocs.yml, it opens the included file, extracts its nav configuration, and imports it into the root navigation.

    To prevent file path conflicts during the merging phase, the plugin uses the site_name of the included file as a directory alias. For example, if an included file has site_name: design-folder-alias, all links within that included navigation are automatically prefixed with design-folder-alias/.

    2. Merging the docs folders

    The plugin creates a temporary directory and moves the root docs/ folder along with the docs/ folders from all included paths into this temporary location. It uses the site_name values from the included files to determine the sub-folder structure within the merged documentation folder.

    Implementation details:

    • Navigation resolution logic: mkdocs_monorepo_plugin/parser.py
    • Folder merging logic: mkdocs_monorepo_plugin/merger.py
    # Example Source mkdocs.yml
site_name: Example Site

plugins:
  - monorepo

nav:
  - Getting Started: README.md
  - Design: '!include teams/design/mkdocs.yml'
  - Contributing: contributing.md

# teams/design/mkdocs.yml
site_name: design-folder-alias

nav:
  - Menus: components/menus.md
  - Tabs: components/tabs.md
    # Example Output (Resolved) mkdocs.yml
site_name: Example Site

plugins:
  - monorepo

nav:
  - Getting Started: README.md
  - Design:
      - Menus: design-folder-alias/components/menus.md
      - Tabs: design-folder-alias/components/tabs.md
  - Contributing: contributing.md

  5. How the mkdocs-monorepo-plugin works

    master

    The mkdocs-monorepo-plugin allows you to manage multiple docs/ folders and multiple mkdocs.yml files within a single MkDocs project. This is particularly useful for monorepos where different teams own different parts of the documentation.

    Core Concepts

    • Multiple docs/ folders: Instead of one massive documentation folder, you can distribute documentation closer to the code it describes.
    • Multiple Navigations: Each subfolder can have its own mkdocs.yml defining its own navigation (nav). The plugin merges these into the root navigation.
    • site_name as a Path Prefix: In subfolder mkdocs.yml files, the site_name key is used to determine the URL path prefix for that documentation set. For example, if site_name is versions/v1, a file named reference.md will be served at /versions/v1/reference/.
    • !include Syntax: In the root mkdocs.yml, you use the !include directive within the nav section to pull in the configuration from subfolder mkdocs.yml files.

  9. Install the monorepo plugin from source

    master

    To develop on the plugin or test changes dynamically, install it in editable mode using pip. This allows changes to the source code to be reflected immediately without re-installation.

    Prerequisites

    • Python 3+ (with Pip)
    • MkDocs 1.0.4 or above
    • Docker
    • Git
    $ git clone git@github.com:backstage/mkdocs-monorepo-plugin.git
$ cd mkdocs-monorepo-plugin/
$ pip install --editable .
$ pip install -r requirements.txt

  10. Use !include to merge mkdocs.yml files

    master

    To merge specific sub-configurations into your main navigation, use the !include syntax in your root mkdocs.yml file. Each included file should be a valid mkdocs.yml containing its own site_name and nav structure.

    # /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

  12. Configure the mkdocs-monorepo-plugin in your root mkdocs.yml

    master

    To use the plugin, add monorepo to the plugins list in your root mkdocs.yml. You can then use the !include syntax in your nav configuration to include subfolder configurations.

    site_name: Cats API

nav:
  - Intro: 'index.md'
  - Authentication: 'authentication.md'
  - API:
    - v1: '!include ./v1/mkdocs.yml'
    - v2: '!include ./v2/mkdocs.yml'

plugins:
  - monorepo