Skip to main content

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.


PyPI version MkDocs Merge Validation Build

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 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. 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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_merge-0.9.0.tar.gz (8.3 kB view details)

Uploaded Source

Built Distribution

mkdocs_merge-0.9.0-py2.py3-none-any.whl (10.0 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file mkdocs_merge-0.9.0.tar.gz.

File metadata

  • Download URL: mkdocs_merge-0.9.0.tar.gz
  • Upload date:
  • Size: 8.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.19

File hashes

Hashes for mkdocs_merge-0.9.0.tar.gz
Algorithm Hash digest
SHA256 19cbf965b61fd81c19fc8c37b0c0baa32b8580c24bdb4da0fa62605351684bc3
MD5 1415018d1d69337bdf6d2f2d30d646df
BLAKE2b-256 7a777cdf2f59a14ad421f10de3f5d18ac4c5a0bf9265818588badffd66cb42f5

See more details on using hashes here.

File details

Details for the file mkdocs_merge-0.9.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_merge-0.9.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 4e1177bb65f73241d313726230747a15a596d88d833062bf4846db3a84b9a42d
MD5 50c980d17aac4f6ae1dcb28e6a00047f
BLAKE2b-256 750e52093993db286dc7f723e5a057f339b0b17b483b94d8296ce60d9106c198

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page