zmerge 📚

zmerge merges the documentation of multiple Zensical projects into one site with working links, a single navigation and one global search. It fills the gap left by the mkdocs-monorepo-plugin until Zensical ships an official solution.

• No custom Zensical, no plugins. zmerge assembles one regular Zensical project and builds it with zensical build.
• One site. One navigation, one global search, one link check across all projects.
• Links that work everywhere. Links between projects use the projects' published URLs and are rewritten into validated relative links when merging.
• Per-project settings. Markdown extensions, plugins, mkdocstrings options and snippets of every project are merged.
• Local or git. Include projects from local paths or straight from git repositories.
• Fast. Hardlinks instead of copies, incremental re-assembly in a few milliseconds, and zmerge serve for live previews.

Installation

uv tool install zmerge --with mkdocstrings-python  # mkdocstrings-python only if you render API docs

Quick start

Include other projects in the nav of an umbrella project's zensical.toml, just like with the mkdocs-monorepo-plugin:

[project]
site_name = "My projects"
site_url = "https://example.github.io/"
nav = [
  { Home = "index.md" },
  { lev = "!include ../lev/zensical.toml" },
  { dame = "!include git+https://github.com/KarelZe/dame-rs.git" },
]

Then build or preview the merged site:

zmerge build --strict
zmerge serve

Add .zmerge/ and .zmerge.toml to your .gitignore. See the documentation for the configuration, linking between projects and limitations, and examples/karelze for a complete umbrella site.

Development

uv sync
uv run pytest
uv run prek run --all-files
uv run zensical serve