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 search index and one link check across all projects.
• Links that work everywhere. Link between projects with their published URLs; zmerge turns them into validated relative links.
• Per-project settings. zmerge merges the markdown extensions, plugins, mkdocstrings options and snippets of every project.
• Local or git, TOML or YAML. Include projects from local paths or git repositories, configured with a zensical.toml or an mkdocs.yml.
• Fast. Hardlinks instead of copies, incremental re-assembly in milliseconds and live previews with zmerge serve.

Installation

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

zm is a short alias of zmerge, e.g. zm serve.

Quick start

Include projects in the nav of an umbrella project's zensical.toml, as 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" },
  { Typer = "!include git+https://github.com/fastapi/typer.git" },
]

[project.markdown_extensions.admonition]
[project.markdown_extensions.toc]
permalink = true

Build or preview the merged site:

zmerge build --strict
zmerge serve

zmerge generates .zmerge/ and .zmerge.toml next to the umbrella zensical.toml. Don't edit or commit them:

printf '.zmerge/\n.zmerge.toml\n' >> .gitignore

Read the documentation for the configuration, links between projects and limitations. The docs are built with zmerge themselves: their example merges lev and Typer from GitHub, see zensical.toml.

Development

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

Warning

zmerge is not affiliated with the Zensical project. It is purely meant as a temporary solution until Zensical ships official support for merging projects, tracked in zensical/backlog#22.