Skip to content

MkDocs Merge

This simple tool allows you to merge the source of multiple MkDocs sites into a single one converting each of the specified sites to a sub-site of the master site.

Supports unification of sites with the same site_name into a single sub-site.

Note: Since version 0.6 MkDocs Merge added support for MkDocs 1.0 and dropped support for earlier versions. See here for more details about the changes in MkDocs 1.0.

PyPI version MkDocs Merge Validation Build

MkDocs-Merge supports Python versions 3.5+ and pypy.

Install

$ pip install mkdocs-merge

Usage

$ mkdocs-merge run MASTER_SITE SITES [-u]...

Parameters

  • MASTER_SITE: the path to the MkDocs site where the base mkdocs.yml file resides. This is where all other sites will be merged into.
  • SITES: the paths to each of the MkDocs sites that will be merged. Each of these paths is expected to have a mkdocs.yml file and a docs folder.
  • -u (optional): Unify sites with the same "site_name" into a single sub-site.

Example

$ mkdocs-merge run root/mypath/mysite /another/path/new-site /newpath/website

A single MkDocs site will be created in root/mypath/mysite, and the sites in /another/path/new-site and /newpath/website will be added as sub-pages.

Original root/mypath/mysite/mkdocs.yml

...
nav:
  - Home: index.md
  - About: about.md

Merged root/mypath/mysite/mkdocs.yml

...
nav:
  - Home: index.md
  - About: about.md
  - new-site: new-site/home/another.md # Page merged from /another/path/new-site
  - website: website/index.md # Page merged from /newpath/website

Development

Dev Install

Clone the repository and specify the dev dependencies on the install command.

Check this StackOverflow answer for more details about the dev dependencies

$ pip install -e .[dev]

Test

The tests can be run using tox from the root directory. tox is part of the development dependencies:

$ tox

Project Status

Very basic implementation. The code works but doesn't allow to specify options for the merging.

Pending work

  • [ ] Refactoring of large functions.
  • [x] GitHub Actions build.
  • [x] GitHub Actions release automation.
  • [x] Publish pip package.
  • [ ] Better error handling.
  • [x] Merge configuration via CLI options.
  • [x] Unit testing (work in progress).
  • [ ] CLI integration testing.
  • [ ] Consider more complex cases.
  • [x] Make MkDocs Merge module friendly: thanks to mihaipopescu