Skip to content

Commit 2e7835c

Browse files
lesnik512claude
andcommitted
docs(planning): defer Zensical cutover with beta/1.0 revisit trigger
Record the Zensical evaluation as a deferred item so the "wait for beta/1.0" decision and its concrete re-check list (page.is_homepage exposure, validation parity for strict docs repos, classic-variant fidelity) survive on main. The 0.0.46 feasibility spike was validated on 2026-07-05 but not kept as a branch; redo the port from mkdocs.yml when revisiting. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 7c4557c commit 2e7835c

1 file changed

Lines changed: 26 additions & 0 deletions

File tree

planning/deferred.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,29 @@
11
# Deferred
22

33
Real-but-unscheduled items, each with a revisit trigger. Add entries lazily.
4+
5+
## Zensical cutover for the docs sites
6+
7+
**What:** Replace Material for MkDocs with [Zensical](https://zensical.org)
8+
(same team) as the builder for the org site and per-project docs sites.
9+
Validated feasible against Zensical 0.0.46 on 2026-07-05: a `zensical.toml`
10+
mirror of `mkdocs.yml` plus a one-block `overrides/main.html` tweak (dedupe the
11+
homepage `<title>` by title text) builds the current site cleanly under both
12+
builders. The spike branch was not kept — redo the port from `mkdocs.yml` when
13+
revisiting.
14+
15+
**Why deferred:** Zensical is still pre-1.0 alpha (0.0.46 as of 2026-07-05, the
16+
latest release) with known gaps versus our current setup.
17+
18+
**Revisit trigger — when Zensical reaches beta/1.0, re-check:**
19+
20+
1. **`page.is_homepage`** (and siblings) exposed to custom templates. Today it
21+
is undefined/falsy under Zensical; the spike works around it by deduping the
22+
homepage `<title>` by title text.
23+
2. **`validation` parity** for the docs-heavy repos (e.g. `faststream-outbox`,
24+
which runs `mkdocs build --strict`): `omitted_files` / orphaned-page
25+
detection and `absolute_links` have **no** documented Zensical equivalent,
26+
and several Zensical validation keys are still marked deprecated. `--strict`
27+
itself and `invalid_links` / `invalid_link_anchors` do map.
28+
3. **`classic` variant fidelity** — that the traditional Material look still
29+
matches the live site after the theme rewrite stabilizes.

0 commit comments

Comments
 (0)