From 2e7835ceef5ed902df3e13c70c7225482e81fc8a Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 5 Jul 2026 11:47:28 +0300 Subject: [PATCH] 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) --- planning/deferred.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/planning/deferred.md b/planning/deferred.md index c58c705..563a9de 100644 --- a/planning/deferred.md +++ b/planning/deferred.md @@ -1,3 +1,29 @@ # Deferred Real-but-unscheduled items, each with a revisit trigger. Add entries lazily. + +## Zensical cutover for the docs sites + +**What:** Replace Material for MkDocs with [Zensical](https://zensical.org) +(same team) as the builder for the org site and per-project docs sites. +Validated feasible against Zensical 0.0.46 on 2026-07-05: a `zensical.toml` +mirror of `mkdocs.yml` plus a one-block `overrides/main.html` tweak (dedupe the +homepage `` by title text) builds the current site cleanly under both +builders. The spike branch was not kept — redo the port from `mkdocs.yml` when +revisiting. + +**Why deferred:** Zensical is still pre-1.0 alpha (0.0.46 as of 2026-07-05, the +latest release) with known gaps versus our current setup. + +**Revisit trigger — when Zensical reaches beta/1.0, re-check:** + +1. **`page.is_homepage`** (and siblings) exposed to custom templates. Today it + is undefined/falsy under Zensical; the spike works around it by deduping the + homepage `<title>` by title text. +2. **`validation` parity** for the docs-heavy repos (e.g. `faststream-outbox`, + which runs `mkdocs build --strict`): `omitted_files` / orphaned-page + detection and `absolute_links` have **no** documented Zensical equivalent, + and several Zensical validation keys are still marked deprecated. `--strict` + itself and `invalid_links` / `invalid_link_anchors` do map. +3. **`classic` variant fidelity** — that the traditional Material look still + matches the live site after the theme rewrite stabilizes.