### Install mkdocs-multirepo-plugin

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Install the plugin using pip. Register it in your mkdocs.yml file.

```bash
pip install mkdocs-multirepo-plugin
```

--------------------------------

### Install Project Dependencies with Poetry

Source: https://github.com/jdoiro3/mkdocs-multirepo-plugin/blob/main/README.md

Use Poetry to install project dependencies and activate the virtual environment for contributing and running tests locally. Assumes Poetry is installed and in your PATH.

```bash
poetry install & poetry shell
```

--------------------------------

### MicroService mkdocs.yml Example

Source: https://github.com/jdoiro3/mkdocs-multirepo-plugin/blob/main/README.md

An example of a mkdocs.yml file located within the docs directory or parent directory of an imported repository, specifying the edit_uri.

```yaml
edit_uri: /blob/master/

nav:
  - Home: index.md
```

--------------------------------

### Check Git Sparse Clone Support

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Verifies if the installed Git version supports sparse checkout, which is required for efficient cloning of specific directories. This function is called internally by the plugin to select the appropriate cloning script.

```python
from mkdocs_multirepo_plugin.util import git_supports_sparse_clone, git_version

version = git_version()
print(version)           # Version(major=2, minor=40, patch=1)
print(version.major)     # 2

supported = git_supports_sparse_clone()
print(supported)         # True  (if git >= 2.25.0)
```

--------------------------------

### Running Local Development Server

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Execute `mkdocs serve` within the imported repository directory to build and serve the site locally, incorporating the parent site's context.

```bash
# Run in the imported repo — the full parent site is reconstructed locally
mkdocs serve
```

--------------------------------

### Initialize and Import DocsRepo

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Demonstrates initializing a DocsRepo object for a remote repository and performing an asynchronous import. Ensure the temporary directory exists and specify import parameters like `docs_dir` and `extra_imports` as needed.

```python
from pathlib import Path
from mkdocs_multirepo_plugin.structure import DocsRepo

temp = Path("/tmp/my_site_temp")
temp.mkdir(exist_ok=True)

repo = DocsRepo(
    name="my-service",
    url="https://github.com/my-org/my-service",
    temp_dir=temp,
    docs_dir="docs/*",       # glob — contents of docs/ are imported
    branch="main",
    edit_uri="edit/main/",
    multi_docs=False,
    config="mkdocs.yml",
    extra_imports=["docs/assets/*"],
    keep_docs_dir=None,      # None = fall back to global setting
)

# Check whether repo was already cloned
print(repo.cloned)   # False

# Async import (sparse clone + flatten docs/ dir)
import asyncio
asyncio.run(repo.import_docs(keep_docs_dir=False))
print(repo.cloned)   # True
print(repo.location) # PosixPath('/tmp/my_site_temp/my-service')

# Load the imported repo's mkdocs.yml config
config = repo.load_config()
print(config.get("nav"))

# Generate the edit URL for a specific page
edit_url = repo.get_edit_url("my-service/index.md", keep_docs_dir=False)
print(edit_url)
# "https://github.com/my-org/my-service/edit/main/docs/index.md"

# Delete the cloned repo from temp dir
repo.delete_repo()
```

--------------------------------

### Basic Repository Import in mkdocs.yml

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Demonstrates the simplest way to import a remote repository's documentation using the `!import` directive. Specify the repository URL to include its entire documentation.

```yaml
nav:
  - Home: index.md

  # Simplest form — clone master branch, docs/ directory
  - MicroService: '!import https://github.com/my-org/microservice-repo'
```

```yaml
# Specify branch
  - Auth Service: '!import https://github.com/my-org/auth-service?branch=main'
```

```yaml
# Custom docs directory
  - Analytics: '!import https://github.com/my-org/analytics?branch=main&docs_dir=site/docs/*'
```

```yaml
# Multiple !import statements in the same nav (resolved asynchronously)
  - section:
    - Service A: '!import https://github.com/my-org/service-a?branch=ok-nav-simple'
    - Service B: '!import https://github.com/my-org/service-b?branch=ok-nav-complex'
```

```yaml
# Deeply nested import
  - Platform:
    - Backend:
      - Core: '!import https://github.com/my-org/core?branch=main'
```

--------------------------------

### GitHub Actions Workflow for Deploying Docs

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

This workflow deploys documentation using mkdocs-multirepo-plugin. It requires a GitHub access token for cloning private repositories and uses environment variables for authentication.

```yaml
# .github/workflows/docs.yml
name: Deploy Docs
on: 
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install mkdocs mkdocs-multirepo-plugin mkdocs-material
      - run: mkdocs build
        env:
          GithubAccessToken: ${{ secrets.DOCS_ACCESS_TOKEN }}
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

```

--------------------------------

### Configure mkdocs.yml with multirepo plugin

Source: https://github.com/jdoiro3/mkdocs-multirepo-plugin/blob/main/README.md

Add the multirepo plugin to your mkdocs.yml file. Optional parameters like 'cleanup' and 'keep_docs_dir' can be configured here.

```yaml
plugins:
  - multirepo:
      # (optional) tells multirepo to cleanup the temporary directory after site is built.
      cleanup: true
      # if set the docs directory will not be removed when importing docs.
      # 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).
      keep_docs_dir: true
```

--------------------------------

### Development Configuration for Imported Repos

Source: https://github.com/jdoiro3/mkdocs-multirepo-plugin/blob/main/README.md

To enable `mkdocs serve` within an imported repository, add the multirepo plugin to the imported repo's configuration with `imported_repo: true`. Specify paths, custom directories, and the branch to use.

```yaml
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
```

--------------------------------

### Configure mkdocs.yml for multirepo plugin

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Register the multirepo plugin and configure its behavior, such as cleanup, keeping the docs directory, and the temporary directory name.

```yaml
plugins:
  - search
  - multirepo:
      cleanup: true        # remove temp_dir after build (default: true)
      keep_docs_dir: false # strip the docs/ prefix from imported paths (default: false)
      temp_dir: temp_dir   # name of the temporary directory (default: "temp_dir")
```

--------------------------------

### Configure Nav Repos for MkDocs Multirepo

Source: https://github.com/jdoiro3/mkdocs-multirepo-plugin/blob/main/README.md

Configure the 'nav_repos' in your mkdocs.yml to specify which repositories to import and which files/directories to include from them. Ensure forward slashes are used for root directory imports.

```yaml
plugins:
  - search
  - multirepo:
      # (optional) tells multirepo to cleanup the temporary directory after site is built.
      cleanup: false
      nav_repos:
        - name: backstage
          import_url: https://github.com/backstage/backstage
          # forward slash is needed in '/README.md' so that only the README.md in the root
          # directory is imported and not all README.md files.
          imports: [
            docs/publishing.md, docs/integrations/index.md, /README.md,
            # asset files needed
            docs/assets/*
            ]
        - name: fast-api
          import_url: https://github.com/tiangolo/fastapi
          imports: [docs/en/docs/index.md]

nav:
  - Backstage:
      - Home: backstage/README.md
      - Integration: backstage/docs/integrations/index.md
      - Publishing: backstage/docs/publishing.md
  - FastAPI: fast-api/docs/en/docs/index.md
  # you can still use the !import statement
  - MkdocStrings: '!import https://github.com/mkdocstrings/mkdocstrings'
```

--------------------------------

### Batch Import Multiple Repositories

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Imports documentation from a list of `DocsRepo` instances concurrently using `asyncio`. This is useful for managing documentation from multiple sources simultaneously. The `keep_docs_dir` argument controls whether the original directory structure is preserved.

```python
import asyncio
from pathlib import Path
from mkdocs_multirepo_plugin.structure import DocsRepo, batch_import

temp = Path("/tmp/batch_temp")
temp.mkdir(exist_ok=True)

repos = [
    DocsRepo(
        name="service-a",
        url="https://github.com/my-org/service-a",
        temp_dir=temp,
        branch="main",
    ),
    DocsRepo(
        name="service-b",
        url="https://github.com/my-org/service-b",
        temp_dir=temp,
        branch="main",
        docs_dir="site/docs/*",
    ),
    DocsRepo(
        name="service-c",
        url="https://github.com/my-org/service-c",
        temp_dir=temp,
        branch="develop",
        multi_docs=True,   # monorepo — import all docs/ dirs
    ),
]

# All three repos are cloned concurrently
asyncio.run(batch_import(repos, keep_docs_dir=False))

# Console output (order varies, all run in parallel):
# 🔳 service-a
# 🔳 service-b
# 🔳 service-c
# ✅ service-b (1.243 secs)
# ✅ service-a (1.891 secs)
# ✅ service-c (2.104 secs)

for repo in repos:
    print(repo.cloned, repo.location)
```

--------------------------------

### Configure repos for auto-generated navigation

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Use the `repos` configuration to import documentation from specified Git repositories. This mode is suitable when the imported repository does not have a `nav` section in its mkdocs.yml.

```yaml
# mkdocs.yml
plugins:
  - search
  - multirepo:
      cleanup: true
      repos:
        # Basic import — docs/ from the default (master) branch
        - section: Backstage
          import_url: 'https://github.com/backstage/backstage'

        # Specify branch and a custom edit URI
        - section: Techdocs CLI
          import_url: 'https://github.com/backstage/techdocs-cli?branch=main&edit_uri=/blob/main/'

        # Import docs from a non-standard directory using a glob
        - section: FastAPI
          import_url: 'https://github.com/tiangolo/fastapi?docs_dir=docs/en/docs/*'

        # Nest the section under a parent path in the nav
        - section: Django REST
          section_path: python
          import_url: 'https://github.com/encode/django-rest-framework'

        # Import all docs directories in a monorepo
        - section: Monorepo Multi Docs
          import_url: 'https://github.com/backstage/mkdocs-monorepo-plugin?multi_docs=True&docs_dir=sample-docs/*'
```

--------------------------------

### Run Unit Tests

Source: https://github.com/jdoiro3/mkdocs-multirepo-plugin/blob/main/README.md

Execute the unit tests using Python's built-in unittest module. This command can be run with either `python` or `python3`.

```bash
$ python[3] -m unittest tests.unittests
```

--------------------------------

### Local Development Mode for Imported Repos

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Configure an imported repository's `mkdocs.yml` to use the parent site's theme, config, and plugins for local development. This requires setting `imported_repo: true` and specifying the parent repository details.

```yaml
# mkdocs.yml inside the imported (child) repository
plugins:
  multirepo:
    imported_repo: true
    url: https://github.com/squidfunk/mkdocs-material   # parent repo URL
    section_name: Backstage                             # section this repo appears under
    branch: master
    yml_file: mkdocs.yml                                # parent repo's mkdocs.yml
    custom_dir: material                                # custom theme dir in parent repo
    # files/dirs from parent repo needed to build the site
    paths:
      - "material/*"
      - "mkdocs.yml"
      - "docs/index.md"
```

--------------------------------

### Run Integration Tests with Docker

Source: https://github.com/jdoiro3/mkdocs-multirepo-plugin/blob/main/README.md

Execute the integration test suite using Docker. This command runs tests across multiple Python versions. The first run may take longer due to image downloads.

```bash
$ ./__tests__/test.sh
```

--------------------------------

### Selective File Import with nav_repos in mkdocs.yml

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Configure `nav_repos` to import specific files or directories from remote repositories. This allows for a custom navigation structure while pulling in only necessary documentation.

```yaml
# mkdocs.yml
plugins:
  - search
  - multirepo:
      cleanup: false
      nav_repos:
        - name: backstage           # becomes the path prefix in nav
          import_url: https://github.com/backstage/backstage
          imports:
            - docs/publishing.md
            - docs/integrations/index.md
            - /README.md            # leading / = root of repo only
            - docs/assets/*         # glob supported

        - name: fast-api
          import_url: https://github.com/tiangolo/fastapi
          imports:
            - docs/en/docs/index.md

nav:
  - Backstage:
      - Home: backstage/README.md
      - Integration: backstage/docs/integrations/index.md
      - Publishing: backstage/docs/publishing.md
  - FastAPI: fast-api/docs/en/docs/index.md
  # mix with !import
  - MkdocStrings: '!import https://github.com/mkdocstrings/mkdocstrings'
```

--------------------------------

### Parse Navigation for Import Statements

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

Recursively walks a MkDocs `nav` list to find `!import` statements and generates `NavImport` objects. These objects allow for in-place replacement of the `!import` string with the actual navigation structure from the imported repository. Ensure `temp_dir` is provided for temporary storage during parsing.

```python
from pathlib import Path
from mkdocs_multirepo_plugin.structure import get_import_stmts

nav = [
    {"Home": "index.md"},
    {"Service A": "!import https://github.com/my-org/service-a?branch=main"},
    {
        "Platform": [
            {"Core": "!import https://github.com/my-org/core?branch=main&docs_dir=docs/*"},
            {"Utils": "!import https://github.com/my-org/utils"},
        ]
    },
]

temp_dir = Path("/tmp/nav_temp")
imports = get_import_stmts(nav, temp_dir, default_branch="master")

for nav_import in imports:
    print(nav_import.section, nav_import.repo.url, nav_import.repo.branch)
# Service A  https://github.com/my-org/service-a  main
# Core       https://github.com/my-org/core        main
# Utils      https://github.com/my-org/utils       master

# After importing, replace the !import strings with the real nav:
# nav_import.set_section_value([{"Home": "service-a/index.md"}, {"API": "service-a/api.md"}])
```

--------------------------------

### Run Integration Tests in Python 3.7 Only

Source: https://github.com/jdoiro3/mkdocs-multirepo-plugin/blob/main/README.md

Optimize integration tests by running them exclusively in Python 3.7. Set the PYTHON_37_ONLY environment variable to enable this mode.

```bash
$ PYTHON_37_ONLY=1 ./__tests__/test.sh
```

--------------------------------

### Import Statement in Nav Section

Source: https://github.com/jdoiro3/mkdocs-multirepo-plugin/blob/main/README.md

Use the !import statement within your mkdocs.yml nav section to include documentation from other repositories. Specify the URL and optionally branch, docs_dir, multi_docs, config, and keep_docs_dir parameters.

```yaml
nav:
  - Home: 'index.md'
  - MicroService: '!import {url}?branch={branch}&docs_dir={path}&multi_docs={True | False}&config={filename}.yml&keep_docs_dir={True | False}'
```

--------------------------------

### URL Parsing Utility Function

Source: https://context7.com/jdoiro3/mkdocs-multirepo-plugin/llms.txt

The `parse_repo_url` function from `mkdocs_multirepo_plugin.structure` parses repository URLs, extracting parameters like branch, docs directory, and extra imports. It handles basic URLs and those with query parameters.

```python
from mkdocs_multirepo_plugin.structure import parse_repo_url

# Simple URL — no query string
result = parse_repo_url("https://github.com/my-org/my-repo")
# {'url': 'https://github.com/my-org/my-repo'}
```

```python
# Full URL with all supported parameters
result = parse_repo_url(
    "https://github.com/my-org/my-repo"
    "?branch=main"
    "&docs_dir=docs/*"
    "&multi_docs=True"
    "&edit_uri=/blob/main/"
    '&extra_imports=["docs/assets/*","CHANGELOG.md"]'
)
# {
#   'url': 'https://github.com/my-org/my-repo',
#   'branch': 'main',
#   'docs_dir': 'docs/*',
#   'multi_docs': 'True',
#   'edit_uri': '/blob/main/',
#   'extra_imports': ['docs/assets/*', 'CHANGELOG.md']
# }
```

```python
# Error: more than one '?' raises ImportSyntaxError
try:
    parse_repo_url("https://github.com/org/repo?branch=main?bad=param")
except ImportSyntaxError as e:
    print(e)  # "The import statement's repo url ... can only contain one ?"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.