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.
Project has been updated to use pyproject.toml
so the version has to be manually synchronized in both __init__.py
and pyproject.toml
.
# Using quotes for zsh compatibility
$ pip install -e '.[dev]'
Test
The tests can be run using tox
from the root directory. tox
is part of the development dependencies:
$ tox
Publishing
The publishing process was updated to use GitHub Actions.
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.9.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4e1177bb65f73241d313726230747a15a596d88d833062bf4846db3a84b9a42d |
|
MD5 | 50c980d17aac4f6ae1dcb28e6a00047f |
|
BLAKE2b-256 | 750e52093993db286dc7f723e5a057f339b0b17b483b94d8296ce60d9106c198 |