Explorer¶

A project layout, explained. Click an entry on the left, use the arrow keys, or follow a deep link. Everything here is also plain HTML: with JavaScript disabled it reads as a list followed by every description.

your-project/

your-project / zensical.toml

zensical.toml

committed

Main configuration for the site

Read when: At startup, and on every change during zensical serve
Format: TOML

Controls how the site is built. Settings live under [project]:

[project]
site_name = "My docs"
watch = ["snippets"]

Watch your snippets

Files under base_path live outside docs/, so list them under watch to rebuild when they change.

Full docs →

your-project / src

src/

committed

Application source code

Contents

main.pyEntry point
settings.jsonRuntime settings
vendor/Third-party code, never edited by hand

your-project / src / main.py

main.py

committed

Entry point

The entry point. Loaded from snippets/main-py.md via body_file, so it can be edited without touching the page.

from app import create_app

if __name__ == "__main__":
    create_app().run(port=8080)

your-project / src / settings.json

settings.json

local only

Runtime settings

Per-machine overrides. Missing keys fall back to defaults.

{ "debug": true, "port": 8080 }

your-project / src / vendor

vendor/

generatedgitignored

Third-party code, never edited by hand

Contents

lib.min.js

your-project / src / vendor / lib.min.js

lib.min.js

generated

Minified bundle. Rebuilt by make vendor.

your-project / docs

docs/

The documentation sources

Contents

index.mdLanding page
README.mdUses an icon override (file instead of md)

your-project / docs / index.md

index.md

Landing page

your-project / docs / README.md

README.md

Uses an icon override (file instead of md)

your-project / .env

.env

gitignoredlocal only

Secrets for local development

Never commit this file.

API_TOKEN=change-me

your-project / Makefile

Makefile

Task runner

Deep links¶

Every node has an address. These links select a node, expand its folder, and scroll the explorer into view:

Node	Link
`src/main.py`	#dirtree-src-main-py
`src/vendor/lib.min.js`	#dirtree-src-vendor-lib-min-js
Second tree: `data/raw/`	#dirtree-data-raw

A second tree on the same page¶

Ids are unique across the page, so two trees can sit side by side in the document. The second one has no root label, and its contents_limit: 3 shortens the "Contents" list of raw/ to three entries and a "Show 2 more" button.

data

data/

Measurement data, raw and processed

Raw files are never edited: every correction happens in the processing step, so processed.nc can always be rebuilt from raw/.

Contents

raw/Untouched instrument output
processed.ncGridded, quality-controlled output

data / raw

raw/

gitignored

Untouched instrument output

Contents

2026-09-26.csv
2026-09-27.csv
2026-09-28.csv
2026-09-29.csv
2026-09-30.csvOne day of underway measurements

data / raw / 2026-09-26.csv

2026-09-26.csv

data / raw / 2026-09-27.csv

2026-09-27.csv

data / raw / 2026-09-28.csv

2026-09-28.csv

data / raw / 2026-09-29.csv

2026-09-29.csv

data / raw / 2026-09-30.csv

2026-09-30.csv

One day of underway measurements

data / processed.nc

processed.nc

generated

Gridded, quality-controlled output

Written by: make process