Skip to content

Zensical

This repository uses Zensical for user-facing documentation in docs/. Durable implementation notes for agents stay in docs/AI/.

Commands

Build the static site:

uv run zensical build

Build from a clean cache:

uv run zensical build --clean

Preview the site while editing:

uv run zensical serve

Preview on a specific address:

uv run zensical serve --dev-addr localhost:8000

Cloudflare Pages deployment

Build from the repository root and publish the site output directory. Use the committed uv.lock so deployment uses the same dependencies as local validation:

python -m pip install uv && uv run --frozen zensical build --clean

Set SKIP_DEPENDENCY_INSTALL=1 in the Pages build environment to let this command handle installation. Cloudflare documents this setting in its build image guide.

pip install . resolves the version ranges in pyproject.toml without using uv.lock. This can select a newer Zensical than the local build. For example, Zensical 0.0.67 rejects the mkdocstrings options inventory_project and inventory_version, which 0.0.42 tolerated. Leave these unsupported options out of zensical.toml; see the supported mkdocstrings settings.

API references

API pages live in docs/api/ and are generated with mkdocstrings from the runtime packages under src/.

Add a public API page with the ::: directive:

::: mp.coins.coins
    options:
      members:
        - CoinsConfig
        - CoinsParallelEnv
        - parallel_env

Then add the page to the API Reference section in zensical.toml. The Python handler is configured there with paths = ["src"], so imports should use the installed public module paths such as mp.coins.coins.

Structure

  • zensical.toml lives at the repository root so the Zensical CLI works without extra flags.
  • docs/index.md is the public documentation home page.
  • docs/substrates/ contains user-facing substrate pages.
  • docs/api/ contains generated API reference pages.
  • docs/development/ contains contributor workflow pages.
  • docs/AI/ is for agent-maintained technical notes and is intentionally not part of the main navigation.

Generated output is written to site/, which is ignored by git.