Skip to content

Migrating from mkdocs-monorepo-plugin

zmerge keeps the !include syntax of the mkdocs-monorepo-plugin:

  1. Migrate the umbrella project and every project from mkdocs.yml to zensical.toml, e.g. with Zensical's migration guide.
  2. Point the !include entries to the projects' zensical.toml or their directories.
  3. Remove monorepo from the plugins.
  4. Build with zmerge build instead of mkdocs build.
[project]
site_name = "My projects"
nav = [
  { Home = "index.md" },
  { lev = "!include ./lev/zensical.toml" },
]

Differences

mkdocs-monorepo-plugin zmerge
A project's site_name is its URL prefix. The prefix is the slug of the nav title, configurable with [zmerge.projects.<id>] prefix.
Nested includes are not supported. Projects can include projects.
Links between projects use paths of the merged site, which break when a project is built on its own. Links between projects use the projects' published URLs and are rewritten when merging.
Plugins and markdown extensions of projects are ignored. They are merged, including per-project mkdocstrings options.
Files at the same path silently overwrite each other. Collisions are errors.
Includes are local files. Includes can be git repositories.
*include expands globs. Not supported yet, see #12.
Per-project edit links. Not supported yet, see #9.