How This Site Works¶
Site conventions
A docs site, run like a product.
The goal is simple: keep navigation stable, make content discoverable at scale, and ensure every model/diagram has a clear home. This page explains how we do that.
Navigation philosophy
Sidebar is curated
The left sidebar is a small tree of durable pages (Services, Methodology, Case Studies). It should stay calm as the site grows.
Blog scales via indexes
We don’t add every post to navigation. Discovery happens through Blog index, search, and topics.
Landing pages do the heavy lifting
Each section has an overview page that routes readers to the right depth: overview → evergreen → posts/models.
URL stability
We avoid renaming published URLs. Once a page is public, it becomes part of the external surface area (bookmarks, references, search).
If a rename is ever unavoidable, we treat it as a migration (and ask first if it affects published links).
What the “Diagram Gallery” means
Gallery = preview layer
It’s a browsing surface: quick scanning of models and patterns.
Inline Mermaid is canonical
The authoritative source remains Mermaid blocks embedded in pages/posts. Gallery images are optional previews.
Deterministic naming
When we add “primary” diagrams, we keep slugs consistent across post, .mmd, and .svg names for long-term sanity.
Where content lives
Blog posts
New posts go in docs/blog/posts/. The Blog index links to them chronologically.
Evergreen pages
Stable concepts live in their section folders (e.g., Methodology, Philosophy). Only truly durable pages go into nav.
Experimental drafts
Keep experimental pages linked from an index page first. Promote to navigation only after they stabilize.
Local preview workflow
For day-to-day writing and design iteration, run the dev server and refresh.
- Use
python -m zensical serve --config-file mkdocs.ymlfor live preview. - Some Zensical builds may not emit HTML via
build; preview viaserveis the reliable workflow here.