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.
MkDocs-Merge supports Python versions 2.7, 3.3, 3.4, 3.5, 3.6 and pypy.
Support for Python 2.6 (MkDocs does support 2.6) was removed due to the use of ruamel.yaml
. More details
here.
Install
$ pip install mkdocs-merge
Usage
$ mkdocs-merge run MASTER_SITE SITES [-u]...
Parameters
MASTER_SITE
: the path to the MkDocs site where the basemkdocs.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 amkdocs.yml
file and adocs
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
...
pages:
- Home: index.md
- About: about.md
Merged root/mypath/mysite/mkdocs.yml
...
pages:
- 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
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.
- Travis CI build.
- Publish pip package.
- Better error handling.
- Merge configuration via CLI options.
- Unit testing (work in progress).
- Consider more complex cases.