zensical¶

MkDocs/Material static site generator wrapper (https://github.com/zensical/zensical)

To install zensical via uv

uv pip install zensical

To upgrade zensical

uv pip install --upgrade zensical

To build the static site

uvx zensical build

To serve the site locally

uvx zensical serve --dev-addr 0.0.0.0:8000

To check the installed version

uvx zensical --version

To run via go-task (project conventions)

task site:build     # build the static site
task site:serve     # serve locally at http://localhost:8000
task site:convert   # convert cheatsheets to zensical markdown pages
task site:check     # check zensical version
task site:update    # update zensical to latest version

Config file: zensical.toml (replaces mkdocs.yml)

Nav is declared as [[project.nav]] TOML array-of-tables. Do NOT hand-edit nav blocks for bulk changes — use the auto-generator:

task generate-docs-nav

Script: uv run python scripts/generate_mkdocs_nav.py Canonical zensical.toml keys: [project] site_name = "My Site" site_url = "https://example.com" repo_url = "https://github.com/owner/repo"

[project.theme] name = "material" features = ["navigation.tabs"]

[project.plugins] search = {} tags = {}

[[project.nav]] Home = "index.md" CI deployment via GitHub Actions: - uses: actions/deploy-pages@v4 (on push to main/master)