Skip to content

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.

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.

Installation

uv tool install zmerge

To render API docs with mkdocstrings, add --with mkdocstrings-python.

Quick start

Create an umbrella project with a regular zensical.toml and include other projects in its nav:

[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" },
]

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

Build the merged site into site/, or preview it with live re-assembly:

zmerge build --strict
zmerge serve

Keep the generated files out of git:

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

Example

examples/karelze merges the docs of lev and dame-rs from GitHub. See the result.

How it works

  1. zmerge reads the umbrella zensical.toml and every included project, from local paths or git repositories.
  2. It assembles one regular Zensical project from the docs and configurations of all projects.
  3. It rewrites what would break in the merged site: links between projects, links out of a project's docs, and per-project mkdocstrings and snippets settings.
  4. It builds the merged project once with zensical build. So there is one search index, and Zensical validates every link across projects.

Re-assembling is incremental and takes a few milliseconds.

Generated files

zmerge writes the merged project next to the umbrella zensical.toml:

  • .zmerge.toml: the merged Zensical configuration.
  • .zmerge/docs/: the docs of all projects below their prefixes, hardlinked to the originals where possible.
  • .zmerge/repos/: projects fetched from git repositories.

These files are internal to zmerge. Inspect them to debug a build, but don't edit or commit them: zmerge overwrites them on every run, and editing a hardlinked file in .zmerge/docs/ changes the original.

Next steps