Tool to merge multiple MkDocs sites into a single directory
Project description
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.
Changelog
Access the changelog here: https://ovasquez.github.io/mkdocs-merge/changelog/
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.
MkDocs-Merge officially supports Python versions 3.8, 3.9 and 3.10. It has been tested to work correctly in previous 3.X versions, but those are no longer officially supported.
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
...
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.
- GitHub Actions build.
- Publish pip package.
- Better error handling.
- Merge configuration via CLI options.
- Unit testing (work in progress).
- CLI integration testing.
- Consider more complex cases.
- Make MkDocs Merge module friendly: thanks to mihaipopescu
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_merge-0.8.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 613ef8ec55b3a8908e28629b02ea52966139f5084f0b1a075549fc700462e629 |
|
MD5 | d4337ef4927324750e74de89050f9f49 |
|
BLAKE2b-256 | 035ce99296f676213b815faff4cf6ee9c9f804c642ade0e1cb3829af2a199710 |