Docs development#

The documentation is built with Zensical, the successor to MkDocs Material. The site configuration lives in zensical.toml at the repository root.

Building the docs locally#

Install the documentation dependencies from the repository root (uv sync installs the dev dependency group, uv pip install adds the docs-only requirements):

uv sync
uv pip install -r docs/requirements.txt

Build the documentation with Zensical:

uv run zensical build --strict

The generated site is written to site/. To preview the documentation while editing, run:

uv run zensical serve

Mermaid diagrams#

Mermaid code fences are supported through Zensical's native SuperFences configuration. Use a standard fenced block:

```mermaid
graph TD
  A[Start] --> B[Finish]
```

Do not use the old mermaid2.fence_mermaid formatter. That formatter was specific to the previous MkDocs Material setup and is not compatible with Zensical's config loader.

Pull request previews#

The docs are deployed for commits on the main branch. Pull requests opened from branches in the main repository also get a public preview at:

https://umami-hep.github.io/umami-preprocessing/pr-<PR-number>/

The workflow posts the preview URL as a pull request comment and updates that comment on later runs. The preview is removed automatically when the pull request is closed. Forked pull requests still build the docs and upload the generated site as an artifact named docs-site, but they do not publish a preview because GitHub does not grant write permissions to those workflows.

If you need the artifact, open the GitHub Actions docs workflow run, download the docs-site artifact, unzip it, and open index.html in your browser.