Multi Repository

As the actual structure for the mkdocs documentation works, it uses a set of submodules stored in the docs/ directory. This is used as a way to keep the documentation in a centralized repository. However, this approach has some limitations, like the fact that the mkdocs monorepo plugin fetches all of the repository files when pulling the most recent changes, which can be a problem if you have a lot of repositories in the docs/ directory. Additional to that using the documentation with the monorepo plugin adds a lot of complexity for the github actions to execute the build process.

To solve this problem, we have tried a new approach to manage the documentation. This approach is based on using the multirepo mkdocs plugin which allows to reference the repository instead of using the submodules.With this approach, we can have a centralized repository for the documentation and reference the repositories that we want to include in the documentation. This way we can have a more organized documentation and avoid the limitations of the monorepo plugin also will ease the repository management and github actions build process as we don't need to manage submodules.

How to use it

To install the multirepo plugin, you need to run the following command:

pip install mkdocs-multirepo-plugin

The way to work with multirepos allos us to use nav_repos, repos and imports to define the repositories and files that we want to include in the mkdocs.yml file.

• nav_repos

plugins:
  - multirepo:
    cleanup: false
    nav_repos:
      - name: backstage
        import_url: https://github.com/backstage/backstage
        imports:
          [
            docs/publishing.md,
            docs/integrations/index.md,
            /README.md,
            docs/assets/*,
          ]
nav:
  - Backstage:
      - Home: backstage/README.md
      - Integration: backstage/docs/integrations/index.md
      - Publishing: backstage/docs/publishing.md

• repos

plugins:
  - multirepo:
      repos:
        - section: Backstage
          import_url: 'https://github.com/backstage/backstage?edit_uri=/blob/mast

• imports

nav:
  - MkdocStrings: "!import https://github.com/mkdocstrings/mkdocstrings"

Limitations of Multirepo plugin

The multirepo brings a lot of benefits to the documentation management, but it also has some limitations to consider:

• The plugin has some conflicts with the search plugin, so it is not possible to use both plugins at the same time.
• The plugin does not support the import of mkdocs.yml documentation that references the root directory of the repository.
• As the way we have defined our documentation, it doesn't adapt well to the current structure defined inside each repository.
• There is a chance to face more issues as the probe of concept doesn't cover all the possible scenarios.

References

For more information about the multirepo plugin, you can check the official documentation: jdoiro3/mkdocs-multirepo-plugin