Zensical User Docs Site¶

The repository now has a Zensical docs site for user-facing documentation.

Configuration lives in the repo root:

zensical.toml

Source Markdown lives in:

docs/

Generated static HTML goes to:

site/

site/ is already ignored by .gitignore via /site, so generated output should not be committed.

Zensical is a dev dependency in pyproject.toml and should be run through uv:

uv run zensical serve
uv run zensical build --strict

The main navigation intentionally includes only the user-facing pages:

overview
getting started
concepts
workflow
algorithms
environments
verification
notebooks
cluster runs
artifacts
API reference
development

docs/AI/ remains internal development documentation. If a durable implementation detail becomes useful to users, summarize the stable part in a top-level docs page instead of making the AI note part of the main navigation.

Every Markdown file under docs/AI/ carries search.exclude: true front matter. Zensical still builds those internal notes because they live below docs/, but they do not appear in site search or the configured navigation. Keep internal notes out of zensical.toml navigation.

Theme overrides¶

Theme template overrides live in docs/overrides/ and are wired up through custom_dir in zensical.toml. Currently this holds only 404.html, which extends main.html to render a branded "Page not found" page.

Because the directory sits inside docs_dir, Zensical also sees it as content. exclude_docs = "overrides/" stops the unrendered Jinja template from being copied to site/overrides/404.html. Zensical honours exclude_docs from 0.0.70; on 0.0.68 it was ignored. The alternatives are a top-level overrides/ next to zensical.toml, which needs no exclusion, or docs/.overrides/, which Zensical skips because it is dot-prefixed but which is easy to miss. After changing either setting, confirm that site/ has no overrides/ directory and that site/404.html still contains the custom text.