# MkDocs Merge
This simple tool allows you to merge the source of multiple [MkDocs](http://www.mkdocs.org/) 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](https://www.mkdocs.org/about/release-notes/#version-10-2018-08-03).
---
[](https://pypi.python.org/pypi/mkdocs-merge)
[](https://github.com/ovasquez/mkdocs-merge/actions/workflows/build.yml)
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
```bash
$ pip install mkdocs-merge
```
## Usage
```bash
$ 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
```bash
$ 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`**
```yaml
...
nav:
- Home: index.md
- About: about.md
```
**Merged `root/mypath/mysite/mkdocs.yml`**
```yaml
...
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](https://stackoverflow.com/a/28842733/2313246) for more details about the `dev`
dependencies
```bash
$ pip install -e .[dev]
```
### Test
The tests can be run using `tox` from the root directory. `tox` is part of the development dependencies:
```bash
$ 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] 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](https://github.com/mihaipopescu)
Raw data
{
"_id": null,
"home_page": "https://github.com/ovasquez/mkdocs-merge",
"name": "mkdocs-merge",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "mkdocs,documentation,merge,multiple",
"author": "Oscar Vasquez",
"author_email": "oscar@vasquezcr.com",
"download_url": "https://files.pythonhosted.org/packages/4a/8b/a6220f7fefe8f4dd7baa161fe0f1088356fda521303e1782bf1835779b80/mkdocs-merge-0.8.0.tar.gz",
"platform": null,
"description": "# MkDocs Merge\n\nThis simple tool allows you to merge the source of multiple [MkDocs](http://www.mkdocs.org/) sites\ninto a single one converting each of the specified sites to a sub-site of the master site.\n\nSupports unification of sites with the same `site_name` into a single sub-site.\n\n## Changelog\nAccess the changelog here: https://ovasquez.github.io/mkdocs-merge/changelog/\n\n> Note: Since version 0.6 MkDocs Merge added support for MkDocs 1.0 and dropped\n> support for earlier versions.\n> See here for more details about the changes in [MkDocs 1.0](https://www.mkdocs.org/about/release-notes/#version-10-2018-08-03).\n\n---\n[](https://pypi.python.org/pypi/mkdocs-merge)\n[](https://github.com/ovasquez/mkdocs-merge/actions/workflows/build.yml)\n\nMkDocs-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.\n\n## Install\n\n```bash\n$ pip install mkdocs-merge\n```\n\n## Usage\n\n```bash\n$ mkdocs-merge run MASTER_SITE SITES [-u]...\n```\n\n### Parameters\n\n- `MASTER_SITE`: the path to the MkDocs site where the base `mkdocs.yml` file resides. This is where all other sites\n will be merged into.\n- `SITES`: the paths to each of the MkDocs sites that will be merged. Each of these paths is expected to have a\n `mkdocs.yml` file and a `docs` folder.\n- `-u` (optional): Unify sites with the same \"site_name\" into a single sub-site. \n\n### Example\n\n```bash\n$ mkdocs-merge run root/mypath/mysite /another/path/new-site /newpath/website\n```\n\nA single MkDocs site will be created in `root/mypath/mysite`, and the sites in\n`/another/path/new-site` and `/newpath/website` will be added as sub-pages.\n\n**Original `root/mypath/mysite/mkdocs.yml`**\n\n```yaml\n...\nnav:\n - Home: index.md\n - About: about.md\n```\n\n**Merged `root/mypath/mysite/mkdocs.yml`**\n\n```yaml\n...\nnav:\n - Home: index.md\n - About: about.md\n - new-site: new-site/home/another.md # Page merged from /another/path/new-site\n - website: website/index.md # Page merged from /newpath/website\n```\n\n## Development\n\n### Dev Install\n\nClone the repository and specify the `dev` dependencies on the install command.\n\nCheck this [StackOverflow answer](https://stackoverflow.com/a/28842733/2313246) for more details about the `dev`\ndependencies\n\n```bash\n$ pip install -e .[dev]\n```\n\n### Test\n\nThe tests can be run using `tox` from the root directory. `tox` is part of the development dependencies:\n\n```bash\n$ tox\n```\n\n## Project Status\n\nVery basic implementation. The code works but doesn't allow to specify options for the merging.\n\n### Pending work\n\n- [ ] Refactoring of large functions.\n- [x] GitHub Actions build.\n- [x] Publish pip package.\n- [ ] Better error handling.\n- [x] Merge configuration via CLI options.\n- [x] Unit testing (work in progress).\n- [ ] CLI integration testing.\n- [ ] Consider more complex cases.\n- [x] Make MkDocs Merge module friendly: thanks to [mihaipopescu](https://github.com/mihaipopescu)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tool to merge multiple MkDocs sites into a single directory",
"version": "0.8.0",
"split_keywords": [
"mkdocs",
"documentation",
"merge",
"multiple"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "035ce99296f676213b815faff4cf6ee9c9f804c642ade0e1cb3829af2a199710",
"md5": "d4337ef4927324750e74de89050f9f49",
"sha256": "613ef8ec55b3a8908e28629b02ea52966139f5084f0b1a075549fc700462e629"
},
"downloads": -1,
"filename": "mkdocs_merge-0.8.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4337ef4927324750e74de89050f9f49",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 9927,
"upload_time": "2023-01-21T06:03:46",
"upload_time_iso_8601": "2023-01-21T06:03:46.463707Z",
"url": "https://files.pythonhosted.org/packages/03/5c/e99296f676213b815faff4cf6ee9c9f804c642ade0e1cb3829af2a199710/mkdocs_merge-0.8.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a8ba6220f7fefe8f4dd7baa161fe0f1088356fda521303e1782bf1835779b80",
"md5": "4668d92da9124ed1951e0e60ff57988e",
"sha256": "f5996dafad35d9d9db0831af36159d6c8cffb74a89fe53afca272b198f0db069"
},
"downloads": -1,
"filename": "mkdocs-merge-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "4668d92da9124ed1951e0e60ff57988e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8697,
"upload_time": "2023-01-21T06:03:48",
"upload_time_iso_8601": "2023-01-21T06:03:48.911814Z",
"url": "https://files.pythonhosted.org/packages/4a/8b/a6220f7fefe8f4dd7baa161fe0f1088356fda521303e1782bf1835779b80/mkdocs-merge-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-21 06:03:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ovasquez",
"github_project": "mkdocs-merge",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "mkdocs-merge"
}
JSON
