DOCSEARCHbyAlgolia
Submit Docs

mkdocs-multirepo-plugin

repository·main·Indexed 41 days ago

https://github.com/jdoiro3/mkdocs-multirepo-plugin

A plugin for MkDocs version 0.8.3 that allows building a single documentation site by importing content from multiple distributed repositories. It supports importing via !import statements in the nav section, RepoConfig, and NavRepoConfig, enabling documentation to remain close to source code while providing a unified user view.

Tokens
4.4K
Snippets
15
Records
20
Agent score
51%

What's inside mkdocs-multirepo-plugin

  1. Import multiple docs directories from a monorepo

    main

    If an imported repository is a monorepo containing multiple docs directories, you can automatically include all of them in your site by setting multi_docs: True in your configuration.

    When multi_docs is enabled, the plugin strips the docs directory from the path. For example, if a project has a structure like project1/docs/index.md, it will be imported as project1/index.md.

    Important Considerations:

    • Navigation: If you use the !import statement in your nav section, ensure the paths reflect the new structure (i.e., remove the docs/ segment from the path).
    • Edit URLs: The edit_urls configuration will continue to map correctly to the original file structure in the remote repository.
    plugins:
  multirepo:
    multi_docs: True

  2. Enable local development in imported repositories

    main

    To allow writers to run mkdocs serve within an imported repository while using the parent site's configuration, themes, and features, you must add the multirepo plugin to the imported repo as well as the parent repo.

    Requirements:

    • The parent repo's plugins and packages must be installed in your local venv.
    • You may need to use git sparse-checkout to manage the paths content.

    Configuration Example: In the imported repository's mkdocs.yml, configure the plugin with imported_repo: true and specify the source URL and required paths.

    plugins:
  multirepo:
    imported_repo: true
    url: https://github.com/squidfunk/mkdocs-material
    section_name: Backstage
    # dirs/files needed for building the site
    # any path in docs will be included. For example, index.md is the
    # homepage of the parent site
    paths: ["material/*", "mkdocs.yml", "docs/index.md"]
    custom_dir: material
    yml_file: mkdocs.yml # this can also be a relative path
    branch: master

  5. How to import documentation using the !import statement

    main

    The !import statement is used within the nav section of your mkdocs.yml to pull documentation from a specific repository into a section of your navigation.

    Syntax: !import {url}?branch={branch}&docs_dir={path}&multi_docs={True | False}&config={filename}.yml&keep_docs_dir={True | False}

    Parameters:

    • {url}: Required. The repository URL (e.g., https://github.com/user/repo).
    • branch={branch}: The branch or tag to use. Defaults to master.
    • docs_dir={path}: The path to the docs directory. Defaults to docs/** (a glob).
    • multi_docs={True | False}: If True, all docs directories will be imported.
    • config={filename}.yml: The name of the configuration file (defaults to mkdocs.yml). This file can reside in the docs directory or the parent directory.
    • extra_imports=["{filename | path | glob}"]: Imports additional directories or files alongside the docs.
    • keep_docs_dir={True | False}: If true, the docs directory is not removed (e.g., section/page.md becomes section/docs/page.md).

    Requirements:

    • The imported repository must have a mkdocs.yml (or the custom config file specified) with a nav section.
    nav:
  - Home: 'index.md'
  - MicroService: '!import https://github.com/user/repo?branch=main&docs_dir=docs/&keep_docs_dir=true'

  6. Run integration tests using Docker

    main

    Integration tests use Docker to run the test suite across multiple Python versions. The first run may take time, but subsequent runs are fast. You can use docker prune to clear the local cache when finished.

    To run the full suite:

    $ ./__tests__/test.sh

    To run faster tests restricted to Python 3.7:

    $ PYTHON_37_ONLY=1 ./__tests__/test.sh

  7. Parse !import statements in MkDocs nav

    main

    The plugin uses !import statements within your nav configuration to pull in documentation from external Git repositories. These statements can include query parameters to customize the import behavior, such as specifying branches, documentation directories, or configuration files.

    Query Parameter Syntax: section: '!import {url}?param1=value1&param2=[item1, item2]'

    Supported Parameters:

    • url: The Git repository URL.
    • branch: The branch to clone (defaults to the repository's default branch).
    • docs_dir: The location of the documentation (supports globs, e.g., docs/*).
    • config: The filename of the MkDocs config (defaults to mkdocs.yml).
    • multi_docs: Boolean. If True, the plugin handles multiple documentation directories.
    • extra_imports: A Python-formatted list of additional directories to import.
    • keep_docs_dir: Boolean. If True, the docs directory is preserved during import.
    nav:
  - External Docs: '!import https://github.com/user/repo?branch=main&docs_dir=docs/*&multi_docs=true'

  8. Configure the multirepo plugin in mkdocs.yml

    main

    Add the multirepo plugin to your plugins section in mkdocs.yml. You can use the following optional configuration keys:

    • cleanup: (boolean) If true, tells multirepo to cleanup the temporary directory after the site is built.
    • keep_docs_dir: (boolean) If true, the docs directory will not be removed when importing docs. Note that when using this with a nav section in an imported repo, you must keep the docs directory in the path (e.g., docs/path/to/file.md).
    plugins:
  - multirepo:
      cleanup: true
      keep_docs_dir: true

  9. Configure repositories via plugins.multirepo.repos

    main

    Use the repos key within the multirepo plugin configuration if you want MkDocs to automatically generate navigation based on the directory structure of the imported repositories. This method is used when the imported repository does not have a nav section in its own mkdocs.yml.

    Note: If the imported repository contains a nav section, this configuration will be ignored as nav takes precedence.

    plugins:
  - multirepo:
      repos:
        - section: Backstage
          import_url: 'https://github.com/backstage/backstage?edit_uri=/blob/master/'
        - section: FastAPI
          import_url: 'https://github.com/tiangolo/fastapi?docs_dir=docs/en/docs/*'
        - section: Pydantic
          import_url: 'https://github.com/samuelcolvin/pydantic?branch=main'

  10. Configure repositories via plugins.multirepo.nav_repos

    main

    Use the nav_repos key when you want to explicitly define which files or directories from an imported repository appear in your main nav section. This allows you to treat imported docs similarly to local docs.

    Parameters in nav_repos:

    • name: The identifier for the repo.
    • import_url: The repository URL.
    • imports: A list of specific files, paths, or globs to include (e.g., docs/assets/*).
    • section_path: (Optional) Used to place the section under a specific menu entry in the navigation.
    plugins:
  - multirepo:
      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

  11. How Nav Import works with !import statements

    main

    The most direct way to import documentation is by using !import statements directly in your mkdocs.yml nav section. This method takes precedence over repos and nav_repos configurations.

    When the plugin encounters a !import string in the navigation, it parses the URL and parameters (like branch, docs_dir, or edit_uri) to fetch and integrate the content.

    Note: If you use both nav and repos, the plugin will log a warning and prioritize the nav section.

    nav:
  - Home: index.md
  - External Guide: "!import https://github.com/user/repo.git?branch=main&docs_dir=docs/guide"

  12. Handle multiple documentation directories with multi_docs

    main

    If a repository contains documentation spread across multiple directories, set multi_docs=True in your !import statement.

    When multi_docs is enabled:

    1. The plugin uses sparse_clone to pull only the necessary directories.
    2. transform_docs_dir() is called to move all files within the identified documentation directories to the parent directory, effectively flattening the structure while maintaining a mapping for edit_uri support.
    3. This ensures that files from different sub-directories are correctly indexed in the main site's file tree.