Package: mkdocs-multirepo-plugin
If you like this plugin and want me to continue maintaining it in my free time, please buy me abeer 🍺or sponser this plugin!mkdocs-multirepo-pluginBuild documentation in multiple repos into one site.FeaturesDistributed Documentation: Keep docs close to the code butfindableon one site.Seperates Concerns: Separate documentation from other files that go into building your mkdocs site (e.g., theme overrides).Fast: Documentation is imported asynchronously, usingasyncio.Simple: All configuration is done within thepluginsornavsections of yourmkdocs.ymlfile.Use in Production: The plugin can be used in a CI/CD pipeline.OS SupportDependenciesNewer versions of Git preferred.SetupInstall plugin using pip:pip install mkdocs-multirepo-pluginNext, add the plugin to yourmkdocs.ymlplugins:-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:trueYou'll now have 3 ways of importing docs:plugins.multirepo.repos: Use this method if you don't have anavsection in the importedmkdocs.ymland want Mkdocs to generate navigation based on the directory structure. If there's anavthis configuration will be ignored sincenavconfiguration takes precedence.plugins.multirepo.nav_repos: Use this if you have anavsection in yourmkdocs.ymland want to refer to imported docs in thenavthe same way as other docs in the repo. This can be used alongside!importstatements.!import: Used to specify docs to import to a section in thenav. The imported repo needs to have amkdocs.ymlfile with anavsection as well.Import StatementThe plugin introduces the!importstatement in your config'snavsection. You can now use the import statement to add a documentation section, where the docs are pulled from the source repo.!import Statement Sections{url}: Onlyrequiredpart of!importstatement (e.g.,https://github.com/{user}/{repo name}).branch={branch}: Tellsmultirepowhat branch (or tag) to use. Defaults tomasterif not supplied. This is the same argument used ingit clone(seehere).docs_dir={path}: The path to thedocsdirectory for the section. Defaults todocs/*(a glob) if not supplied.multi_docs={True | False}: If set toTruealldocsdirectories will be imported (more infohere).config={filename}.yml: Tellsmultirepothe name of the config file, containing configuration for the plugin. The default value is alsomkdocs.yml. This config file can live within the docs directoryorin the parent directory.extra_imports=["{filename | path | glob}"]: Use this if you want to import additional directories or files along with the docs.keep_docs_dir={True | False}: If set the docs directory will not be removed when importing docs (i.e.,section/page.mdbecomessection/docs/page.md)nav:-Home:'index.md'-MicroService:'!import{url}?branch={branch}&docs_dir={path}&multi_docs={True|False}&config={filename}.yml&keep_docs_dir={True|False}'MicroService mkdocs.yml (located within the docs directory or the parent directory)edit_uri:/blob/master/nav:-Home:index.mdThings to Note:If using!importin thenav, the imported repo must have amkdocs.yml(or another filename with a?config={filename}.yml) file with anavsection located in either thedocsdirectory or the root directory.navtakes precedence overrepos(see below).{path}can also be aglob(e.g.,docs/*).Repos ConfigIf you'd preferMkDocsto build the site nav based on the directory structure, you can define your other repos within thepluginssection.plugins:-search-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:truerepos:# There will be a navigation section with this section name-section:Backstage# you can define the edit uri pathimport_url:'https://github.com/backstage/backstage?edit_uri=/blob/master/'-section:Monorepoimport_url:'https://github.com/backstage/mkdocs-monorepo-plugin?edit_uri=/blob/master/'-section:'Techdocs-cli'# note that the branch is still specified in the urlimport_url:'https://github.com/backstage/techdocs-cli?branch=main&edit_uri=/blob/main/'-section:FastAPIimport_url:'https://github.com/tiangolo/fastapi?docs_dir=docs/en/docs/*'-section:Monorepo Multi Docsimport_url:https://github.com/backstage/mkdocs-monorepo-plugin?multi_docs=True&docs_dir=sample-docs/*-section:'DjangoREST'section_path:python# Put this under the python menu entryimport_url:'https://github.com/encode/django-rest-framework'-section:'CookiecutterPypackage'section_path:python# Put this under the python menu entryimport_url:'https://github.com/zillionare/cookiecutter-pypackage'-section:'Pydantic'section_path:python# Put this under the python menu entryimport_url:'https://github.com/samuelcolvin/pydantic?branch=main'Nav Repos Configplugins:-search-multirepo:# (optional) tells multirepo to cleanup the temporary directory after site is built.cleanup:falsenav_repos:-name:backstageimport_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 neededdocs/assets/*]-name:fast-apiimport_url:https://github.com/tiangolo/fastapiimports:[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:'!importhttps://github.com/mkdocstrings/mkdocstrings'RunOnce you're done configuring, run eithermkdocs serveormkdocs build. This willimportthe docs into a temporary directory and build the site.Additional Featuresα Multiple Docs Directories in Imported Repo (Alpha)If an imported repo is a monorepo (i.e., has multipledocsdirectories),multirepoautomatically includes them in the site whenmulti_docsis set toTrue.SupposeMicroservice'sdirectory structure is this.├───mkdocs.yml (required if nav section is defined)
├───README.md
├───project1
│   └───src
│   └───docs
│       └───assets
|         index.md
|         technical.md
├───project2
│   └───src
│   └───docs
│         index.mdBy default, this directory turns into this.├───mkdocs.yml (required if nav section is defined)
├───README.md
├───project1
│   └───assets
|     index.md
|     technical.md
├───project2
│     index.mdNote:If using the nav!importstatement, make sure the nav paths reflect the new directory structure, which doesn't includedocsdirectories.edit_urlswill still map to underlying markdown file based on the actual directory structure in the remote's repository.Use in CI/CDIf you want to use the plugin within Azure Pipelines or Github Actions, you'll need to define an access token.Azure PipelinesYou'll need to define anAccessTokenenvironment variable for themkdocs buildstep. The access token should have access tocloneall repos.Github ActionsYou'll need to define anGithubAccessTokenenvironment variable for themkdocs buildstep. The access token should have access tocloneall repos. This can be a personal access token or one from a GitHub App.Azure Pipeline Step Example-script:|source ./env/bin/activatemkdocs buildenv:AccessToken:$(System.AccessToken)displayName:'BuildMkDocsSite'β Development in Imported Repos (Beta)Formkdocs serveto work properly in an imported repo (a repo that is imported in the parent site),you will need to add the multirepo plugin within the imported repo as well as the parent repo, including the following configuration.Notes:You will also need to havepluginsandpackagesthe parent repo uses installed within your localvenv.See documentation on thesetgit command forsparse-checkoutif you are confused with whatpathscan contain.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: masterWriters can now runmkdocs servewithin their local repo, using the main site's configuration, custom theming and features. This means all development is distributed, without technical writers having to switch repos.Backstage with Material themeContributingYou'll need to installPoetryand Git to contribute and run tests locally.SetupAssumes you havepoetryinstalled and in your path~ poetry install & poetry shellRunning TestsTests were modeled off ofmkdocs-monorepo-plugin. To run the test suite you'll need:PythonGitDockerMkDocsIntegration TestingThe command below will use Docker to run our test suites in numerous Python versions. It may take some time on first run, but should be very fast afterwards. When you're done, feel free to rundocker pruneto clear them from your local cache. We use theslimversions of the publicpythonimages fromDocker Hub.$ ./__tests__/test.shFor faster tests, you can opt to run in Python 3.7 rather than all supported Python versions:$ PYTHON_37_ONLY=1 ./__tests__/test.shUnit Testing$ python[3] -m unittest tests.unittests