Skip to content

Links

Links within a project keep working, because each project keeps its folder structure below its prefix. zmerge rewrites links that would break in the merged site, so a project's docs build both on their own and merged.

Link to another project with the absolute URL of its published site:

The engine uses an [opening book](https://karelze.github.io/dame-rs/design/#opening-book).

The link works when the project is built on its own. When merging, zmerge turns every link into the site_url of the umbrella project or an included project into a relative link to the merged page:

The engine uses an [opening book](../dame/design.md#opening-book).

Zensical then validates the link, anchors included. zmerge understands directory URLs (design/), .html URLs (design.html), index pages and assets. It leaves a link into a project's site that matches no merged page unchanged and warns.

Tip

Set site_url in every project. zmerge leaves links to other sites under the umbrella's site_url unchanged, without a warning.

Relative links out of a project's docs_dir, e.g. to ../LICENSE or ../src/, would resolve to unrelated files in the merged site. zmerge turns them into links to the file in the project's repository, built from repo_url and the branch in edit_uri:

[project]
repo_url = "https://github.com/KarelZe/lev"
edit_uri = "edit/main/docs/"

[license](../LICENSE) becomes [license](https://github.com/KarelZe/lev/blob/main/LICENSE). zmerge supports GitHub and GitLab (-/edit/main/docs/) style edit URIs. Without repo_url and edit_uri, it leaves the link unchanged and warns.

Link from the umbrella project's pages to project pages with their merged path, e.g. [lev](lev/index.md), or with absolute URLs as above.

What is rewritten

zmerge rewrites the destinations of inline links, images and reference definitions in Markdown, but not inside code. Links in raw HTML and in snippets aren't rewritten yet, see limitations.