Evaluate Zensical Beta migration: validation and template blockers

Migrated from planning/deferred.md, retired in the move to the PR-body-as-spec convention (#50).

Goal and current status

Replace Material for MkDocs with Zensical as the builder for the org site and per-project docs sites.

Rechecked 2026-11-14 against Zensical 0.1.1. The release gate has fired: 0.1.1 shipped November 10 and is classified Beta. Re-evaluation can proceed, but migration is not yet verified ready. Validation parity remains the main blocker; local template fixes and output verification are also required.

The recorded migration deadline remains 2027-05-05, when Material for MkDocs critical maintenance ends (see upstream announcement).

Keep mkdocs.yml during evaluation and set theme.variant: classic, as recommended by the migration guide. A TOML rewrite is unnecessary. The old July spike branch was not retained.

Verified build findings

Scope: temporary copies of the seven current docs sites outside lite-bootstrap: .github, modern-di, that-depends, httpware, semvertag, faststream-outbox and faststream-redis-timers. The org checkout matched origin/main at 097e571; the other sites were tested from local working copies, not asserted to match remote HEADs. Production files were unchanged. lite-bootstrap was excluded and remains unverified.

With theme.variant: classic, the org site passes zensical build --strict. The other six fail with RuntimeError: unknown method: string has no method named endswith in their custom main.html overrides.
Replacing config.site_url.endswith('/') with config.site_url[-1:] == '/' in temporary overrides makes all seven strict builds pass. This is a required migration fix, not a production change already made.
Configured exclude_docs works: no agents/ or adr/ HTML is emitted by the six sites excluding those paths. A minimal fixture confirms both directories stay excluded. that-depends has no such exclusions and emits its three agents pages; that is not an exclusion regression.
modern-di emits both llms.txt (9,872 bytes) and llms-full.txt (548,787 bytes) with its current plugin configuration. that-depends also emits both files, correcting the earlier claim that only modern-di uses llmstxt. Generation is verified; content parity is not.
The org homepage title and social titles equal Modern Python. Sites using nav.homepage produce the expected homepage social titles. Contrary to the previous issue body, that-depends still uses page.is_homepage; its generated homepage social title is Quick-Start · that-depends and needs the same workaround.

Remaining blockers and completion checks

1. Preserve validation behavior, or explicitly decide what loss is acceptable

The v0.1.1 config mapper still drops omitted_files and unrecognized_links. It recognizes absolute_links only for the relative_to_docs resolution mode; the existing absolute_links: warn does not preserve MkDocs warning behavior. Link and anchor validation remain supported.

Executed regression probe: with an explicit nav containing only index.md, an additional orphan.md, and validation.omitted_files: warn, Zensical strict mode reports no issues and publishes orphan/index.html. MkDocs 1.6.1 strict mode exits 1 and reports the omitted page. Passing Zensical strict mode therefore does not establish validation parity.

No upstream orphan-page issue was identified in this investigation. backlog#63 concerned not_in_nav, not orphan detection. The validation docs still provide no orphan-page equivalent.

Restore equivalent diagnostics through upstream support or a separate check, or record an explicit decision accepting each lost check.
Verify strict-mode failures with negative fixtures, including omitted pages and the existing link-warning cases.

2. Make template overrides compatible

Replace .endswith() in all six tested project overrides with a compatible expression; rerun strict builds.
Replace page.is_homepage in that-depends with nav.homepage and page.url == nav.homepage.url; verify homepage and inner-page metadata.
Inspect lite-bootstrap separately before migrating it.

nav.homepage is explicitly exposed in the v0.1.1 navigation view. The page model has no built-in is_homepage field.

3. Verify llmstxt content parity

Native llmstxt support accepts the current settings, including sections, globs and full_output; generation is no longer an upstream blocker.

Compare MkDocs and Zensical output for modern-di and that-depends: sections, glob expansion, code blocks, page coverage and exclusion of internal content.

4. Verify classic visual and deployment behavior

Compare classic output against the current sites in light/dark modes and mobile layouts, including navigation and custom CSS.
Verify generated titles, social metadata, assets and excluded directories in the migration PRs.
Update each site's build/hosting configuration and demonstrate a successful build, including that-depends' Read the Docs setup.

No visual parity or deployment verification was performed in this check.

Reproduction

Run in temporary copies, with theme.variant: classic for the site builds:

uv tool run --from zensical==0.1.1 zensical build -f mkdocs.yml --strict
uv tool run --from mkdocs==1.6.1 mkdocs build -f mkdocs.yml --strict

For the orphan/exclusion probe, create docs/index.md, docs/orphan.md, docs/agents/private.md and docs/adr/private.md with simple headings and use:

site_name: Probe
nav:
  - Home: index.md
exclude_docs: |
  /agents/
  /adr/
validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn
  anchors: warn

docs: adopt the PR-body-as-spec convention, retiring planning/ and ar…

This was generated by AI during triage.

Triage Notes

Parked as needs-triage: the revisit trigger has not fired.

Gate check (2026-09-06): Zensical is at 0.0.59 on PyPI. The issue's snapshot was 0.0.46 on 2026-07-05, so upstream has shipped 13 releases since, but is still 0.0.x and has not reached the beta/1.0 threshold this issue is conditioned on.

Confirmed not started: there is no zensical.toml in this repo and no Zensical reference anywhere in the tree. As the body notes, the spike branch was not kept, so the port is a redo from mkdocs.yml whenever it happens.

The four re-check criteria remain open. I did not re-test any of them against 0.0.59, since the version gate has not fired:

page.is_homepage and siblings exposed to custom templates
validation parity for the docs-heavy repos: omitted_files / orphaned-page detection and absolute_links
classic variant fidelity against the live site
a not_in_nav equivalent, which this repo now relies on to keep docs/adr/ out of the site menu while still building it

Next action: re-run this gate when Zensical announces beta or 1.0. There is no work to do before then, for a human or an agent.

Revisit check — 2026-09-06

Ran the trigger against Zensical 0.0.59. It has not fired. Every claim below is cited to a
primary source: the PyPI JSON API, the zensical/zensical and zensical/ui source at the stated
tags, zensical.org, mkdocs.org, and squidfunk.github.io/mkdocs-material. Nothing was installed or
built — where docs are silent, the finding is read from source and labelled as such.

Paths are repo-relative within the org; org/ means this repo.

Verdict: the trigger has not fired — Zensical is still self-described alpha (0.0.59), all three original blockers remain open, and a fourth has appeared (exclude_docs is unsupported), so keep the issue open with an updated trigger and re-check after the beta release.

All findings below apply to Zensical 0.0.59 (released 2026-09-03), its docs at zensical/docs
commit 94cc5b4 (2026-09-03), and the bundled theme UI zensical/ui v0.0.27 (2026-09-02),
unless stated otherwise. Delta baseline is 0.0.46/0.0.47 (the spike, 2026-07-05).

Trigger status

Applies to: 0.0.59.

Fact	Value	Source
Latest release	`0.0.59`, uploaded 2026-09-03T18:40:51Z	`https://pypi.org/pypi/zensical/json` (`info.version`, `releases`)
PyPI classifier	`Development Status :: 3 - Alpha`	same
Releases since the spike	13 (`0.0.47` 2026-07-05 → `0.0.59` 2026-09-03; no `0.0.49`)	same
Repo HEAD	`444b71e` "chore: release v0.0.59", 2026-09-03	`https://github.com/zensical/zensical` (`git log -1`)

The project's own words, verbatim:

"Zensical follows [semantic versioning] and currently uses 0.0.x versioning
(alpha / development releases). We're approaching a beta release, after
which we'll transition to 0.x versioning. Once we reach a stable 1.0 release,
the standard semantic versioning rules will apply more strictly."
— https://zensical.org/docs/upgrade/#versioning (source: zensical/docs, docs/upgrade.md L50–53)

"Zensical is currently alpha software and we are iterating rapidly."
— https://zensical.org/about/roadmap/, "Foundation" section (read 2026-09-06)

No beta or 1.0 date is given anywhere; the roadmap explicitly declines dates ("Rather than
promising concrete dates, we prefer to make our work visible"). Beta has not been reached.

Delta since 2026-07-05 that matters to us

0.0.53 — strict is now settable in mkdocs.yml / zensical.toml, not just --strict
(https://github.com/zensical/zensical/releases/tag/v0.0.53, "support strict configuration option (#840)").
0.0.56 — unresolved_references further retired: "Please disable unresolved_references -
it is not supported anymore"; autorefs checking moved under invalid_links
(https://github.com/zensical/zensical/releases/tag/v0.0.56).
0.0.58 — build-architecture rewrite (ZRX scheduler); six new plugin replacements
(meta, redirects, minify, tags, literate-nav, awesome-nav); 30–40 % less peak memory
(https://github.com/zensical/zensical/releases/tag/v0.0.58).
Nothing in 0.0.47–0.0.59 release notes touches page.is_homepage, exclude_docs,
omitted_files, or absolute_links.

Blocker 1 — `page.is_homepage` in custom templates

Applies to: Zensical 0.0.59 / ui v0.0.27. Status: still broken, and now demonstrably so at the source level.

Not documented anywhere. Zensical's theme-customization page documents custom_dir, the
block list, and MiniJinja compatibility but publishes no template-context/variable reference at all
(https://zensical.org/docs/customization/, source docs/customization.md). So this is
"not documented", not "documented as absent".

Source says it does not exist. In crates/zensical/src/structure/page.rs (0.0.59), the render
context is built in Page::render_template as
context! { generator, nav, base_url, extra_css, extra_javascript, config, page => self, ..variables }.
The serialized page object is PageData + Page, whose fields are exactly: url,
canonical_url, edit_url, path, title, plus the flattened Markdown fields meta,
content, toc (crates/zensical/src/structure/markdown.rs), plus ancestors, previous_page,
next_page. There is no is_homepage — grep -rn is_homepage over the whole zensical/zensical
repo at 0.0.59 returns nothing.

And Zensical's own theme still references it, so the failure is silent:
zensical/ui src/base.html L89 (tag v0.0.27) reads

{% elif page.title and not page.is_homepage %}
  <title>{{ page.title | striptags }} - {{ config.site_name }}</title>

page.is_homepage is simply undefined → falsy → the homepage falls through the page.meta.title
branch. This is precisely the duplicated <title> the 2026-07 spike papered over.

MkDocs documents is_homepage as a Page property ("Evaluates to True for the homepage of the
site and False for all other pages"), with the exact idiom our overrides use —
https://www.mkdocs.org/dev-guide/themes/ (Page object reference).

Supported way to special-case the home page today

There is no documented one. From source, the workable, builder-portable expression is a URL
comparison against the navigation homepage:

nav.homepage is exposed to templates — NAVIGATION_FIELDS = ["items", "homepage", "hash"]
in crates/zensical/src/structure/nav/view.rs L38, resolved at L161–163 by serializing
navigation.homepage (a NavigationItem, which carries url).
So {% if nav.homepage and page.url == nav.homepage.url %} works under Zensical and equally
under MkDocs (nav.homepage is part of the MkDocs Navigation object).

This is a source-derived workaround, not documented behaviour, and it is not the fix the issue's
trigger asked for.

Blast radius, corrected

The issue implies only the org site is affected. In fact all four override files use
page.is_homepage:

org/overrides/main.html (twice: htmltitle and extrahead)
faststream-outbox/overrides/main.html (extrahead, og/twitter title)
modern-di/overrides/main.html (same)
lite-bootstrap/overrides/main.html (same)

Under Zensical, each would silently emit a wrong og:title/twitter:title on the home page, and
the org site would additionally get a doubled <title>.

Blocker 2 — validation parity

Applies to: Zensical 0.0.59. Status: partially improved (strict is fully there), core gap unchanged.

MkDocs' tree (https://www.mkdocs.org/user-guide/configuration/#validation; a bare top-level key
such as absolute_links: sets both nav: and links:) vs Zensical
(https://zensical.org/docs/setup/validation/, source docs/setup/validation.md), cross-checked
against the mapper in python/zensical/config.py L613–653 of zensical/zensical @ 0.0.59:

MkDocs key	Zensical equivalent	Deprecated?	Evidence
`validation.links.not_found` (`unrecognized_links`'s sibling)	`invalid_links`	No — first-class, on by default	docs `setup/validation.md` § `invalid_links`; `config.py` L642 maps `not_found != "ignore"`
`validation.links.anchors` / `invalid_link_anchors`	`invalid_link_anchors`	No — first-class, on by default	docs § `invalid_link_anchors`; `config.py` L644
`validation.nav.omitted_files` (orphan pages)	none	n/a	Not in Zensical's docs at all; `config.py` L625–626 comment: "we only support validation of links right now, as navigation will change significantly". Officially acknowledged as an open backlog item: `https://github.com/zensical/backlog/issues/63` (OPEN, opened 2025-11-20) — "Right now, Zensical [does] not warn about Markdown pages that are not referenced in the navigation … as MkDocs does"
`validation.{nav,links}.absolute_links` (incl. `relative_to_docs`)	none	n/a	Absent from `setup/validation.md`; not in the mapper's key set (`config.py` L614–622), so silently dropped
`validation.links.unrecognized_links`	none	n/a	Same as above — silently dropped
`--strict`	`zensical build --strict`, and `strict: true` in `mkdocs.yml` since 0.0.53	No	docs § "Strict mode"; `https://github.com/zensical/zensical/releases/tag/v0.0.53`
— (Zensical-only)	`unresolved_references`, `unresolved_footnotes`, `unused_definitions`, `unused_footnotes`, `shadowed_definitions`, `shadowed_footnotes`	Yes — docs: "The following checks have been deprecated in their current form"; 0.0.56 notes go further: `unresolved_references` "is not supported anymore"	docs § "Deprecated checks"; release v0.0.56

Two behaviours worth knowing, both from python/zensical/config.py @ 0.0.59:

Unsupported validation keys are silently ignored — the mapper only reads links, not_found,
anchors, and Zensical's own eight keys ("We only support a subset of MkDocs' validation
settings, so we ignore the ones we don't support", L639–640). No warning is emitted.
MkDocs' three-level severities collapse to booleans: anything other than "ignore" means "on".
warn and info are indistinguishable.

Replacement is promised but unshipped: the deprecated checks will "be replaced with functionally
equivalent ones once we publish our Python Markdown parser and integrate it with Zensical"
(docs/setup/validation.md). Nothing in the docs promises replacements for omitted_files or
absolute_links.

What `faststream-outbox` actually depends on

faststream-outbox/mkdocs.yml declares, as top-level (i.e.
nav-and-links) keys:

validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn
  anchors: warn

CI runs just docs-build → uvx --with-requirements docs/requirements.txt mkdocs build --strict
(faststream-outbox/justfile L56, invoked by
.github/workflows/docs.yml). modern-di and lite-bootstrap carry the identical validation:
block; the org repo has none and relies on mkdocs build --strict alone
(org/.github/workflows/ci.yml, deploy.yml).

Net effect of switching that repo to Zensical today: --strict still fails the build, and
anchors still maps, but three of its four declared checks vanish without a warning — orphaned
pages, absolute links, and unrecognized relative links stop being caught. Because
validation.omitted_files is what currently keeps docs/agents/ and docs/adr/ honest alongside
exclude_docs, that is a real regression in the repo the issue itself calls the hard case.

Blocker 3 — `classic` variant fidelity

Applies to: Zensical 0.0.59. Status: resolved as far as primary sources can settle it — classic is documented, current, and recommended for exactly our case.

Two variants exist, modern (default — variant is commented out in the bootstrap config,
python/zensical/bootstrap/zensical.toml L22) and classic.
"The classic variant preserves the appearance of Material for MkDocs, while both variants
retain the same HTML structure. We recommend using classic when moving an existing Material for
MkDocs project or when custom CSS and JavaScript depend on its established appearance."
— https://zensical.org/docs/compatibility/mkdocs/migration/#theme-variant
"Zensical supports the complete settings surface and provides a classic theme variant that
preserves the look of Material for MkDocs"; "[additional CSS] and [JavaScript] work without
changes when using the classic theme" — https://zensical.org/docs/compatibility/mkdocs/
Still actively maintained, not frozen: 0.0.47's notes describe features integrating "with the
theme in both classic and modern variants"
(https://github.com/zensical/zensical/releases/tag/v0.0.47); the roadmap states "You can keep
the original look of Material for MkDocs, or opt into the new, modern design" and claims
"Identical HTML output" (https://zensical.org/about/roadmap/).

Caveat: pixel-level fidelity against our live sites is a claim only a build can settle, and the
spike branch was not kept. Nothing in primary sources contradicts it; nothing verifies it either.

Config-surface gap check

Union of keys actually used across org/, faststream-outbox/, modern-di/, lite-bootstrap/
(the only four repos with a mkdocs.yml; chat-app, modern-di-faststream, modern-di-pytest,
litestar-sqlalchemy-template have none). Status is for Zensical 0.0.59.

Key (as used)	Zensical equivalent	Evidence
`site_name`, `site_url`, `site_description`	Yes, same names	`https://zensical.org/docs/setup/basics/`
`repo_url`, `repo_name`, `edit_uri`	Yes, same names	`https://zensical.org/docs/setup/repository/`
`docs_dir`	Yes	`setup/basics.md#docs_dir`
`nav`	Yes, unchanged	`https://zensical.org/docs/compatibility/mkdocs/migration/`
`exclude_docs`	NO — documented as unsupported	migration.md § "Unsupported settings" lists `exclude_docs`, `draft_docs`, `not_in_nav`, `hooks`, `remote_branch`, `remote_name`; tracked at `https://github.com/zensical/backlog/issues/65` (OPEN, 2025-11-22). Source confirms: no `exclude_docs` handling in `python/zensical/config.py`, and the Rust `Project` struct (`crates/zensical/src/config/project.rs` L48) has no `deny_unknown_fields`, so the key is silently dropped — `docs/adr/` and `docs/agents/` would be published with no warning
`theme.name: material`	Yes — "we deliberately keep the name of the default theme as `material`"	`https://zensical.org/docs/customization/#theme-configuration`
`theme.custom_dir`	Yes; resolved relative to the config file	`https://zensical.org/docs/customization/#configuring-overrides`
`theme.logo`, `theme.favicon`	Yes	`https://zensical.org/docs/setup/logo-and-icons/`
`theme.icon.{edit,view,repo}`	Yes	`https://zensical.org/docs/setup/repository/`
`theme.palette` (list, `media`/`scheme: default	slate`/`toggle.icon`/`toggle.name`)	Yes
`palette.primary: custom` + `accent: custom` (CSS vars in `extra_css`)	Yes, documented idiom	`https://zensical.org/docs/setup/colors/` (`primary: custom` + `--md-primary-fg-color*` in extra CSS)
`theme.features`: `navigation.instant`, `.top`, `.sections`, `.expand`, `.footer`	Yes	`https://zensical.org/docs/setup/navigation/`, `.../setup/footer/`
`theme.features`: `header.autohide`, `announce.dismiss`	Yes	`https://zensical.org/docs/setup/header/`
`theme.features`: `content.code.copy`, `content.code.annotate`	Yes	`https://zensical.org/docs/authoring/code-blocks/`
`theme.features`: `content.action.edit`, `content.action.view`	Yes	`https://zensical.org/docs/setup/repository/`
`theme.features`: `search.suggest` (org only)	Undocumented but implemented	Absent from `docs/setup/search.md` (only `search.highlight` is documented); present in the UI's feature union, `zensical/ui` `src/assets/javascripts/_/index.ts` L58
`extra_css`	Yes	`https://zensical.org/docs/customization/#additional-css`
`extra.social` (icon/link/name)	Yes	`https://zensical.org/docs/setup/footer/`
`validation.*`	Partial — see Blocker 2
`markdown_extensions`: `admonition`, `attr_list`, `def_list`, `md_in_html`, `toc.permalink`	Yes, all listed as natively supported	`https://zensical.org/docs/compatibility/markdown/python-markdown/`
`markdown_extensions`: `pymdownx.{highlight(anchor_linenums,line_spans,pygments_lang_class), inlinehilite, snippets, superfences, tabbed(alternate_style), details}`	Yes, all listed with those exact options	`https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/`
`pymdownx.emoji` with `!!python/name:material.extensions.emoji.*` (org only)	Yes — the YAML tag ports, and the `material.` namespace is auto-rewritten	Docs prescribe `!!python/name:zensical.extensions.emoji.twemoji` (`.../python-markdown-extensions/#emoji`); source shim rewrites it for you: `python/zensical/config.py` L177–181 replaces `"material.extensions"` → `"zensical.extensions"` (and `materialx` → `zensical.extensions`) in the raw YAML before parsing. The rewrite is source-level, not documented
`markdown_extensions`: `codehilite: {use_pygments: true}` (all three project repos)	Undocumented; source shows pass-through	Not listed among supported extensions on either compatibility page. `python/zensical/config.py::_convert_markdown_extensions` (L1197+) has no allowlist and `python/zensical/markdown/render.py` L76–79 hands the names straight to `Markdown(extensions=...)`, so the stock Python-Markdown extension would load. Rendering/styling parity unverified
`plugins.llmstxt` (`modern-di` only)	NO	Not in the supported-plugin list (`https://zensical.org/docs/compatibility/mkdocs/plugins/`, which covers autorefs, awesome-nav, glightbox, literate-nav, macros, markdown-exec, meta, minify, mkdocstrings, offline, redirects, search, section-index, table-reader, tags). Tracked at `https://github.com/zensical/backlog/issues/83` (OPEN, 2026-01-05)
Template overrides using MiniJinja-incompatible Jinja	Mostly fine — Material adapted its templates by 9.6.18; our repos pin `mkdocs-material>=9.7.5` (org) / `>=9,<10` (projects)	`https://zensical.org/docs/compatibility/mkdocs/migration/#templates-and-overrides`

Flagged — no documented equivalent: exclude_docs (silently ignored), validation.omitted_files,
validation.absolute_links, validation.unrecognized_links (all silently ignored),
plugins.llmstxt. Flagged — undocumented but working per source: search.suggest,
codehilite, the material.extensions.emoji namespace rewrite, and nav.homepage as an
is_homepage substitute.

The issue's closing note is stale: not_in_nav is no longer used anywhere in the org. Three of
the four repos use exclude_docs instead (org/mkdocs.yml "Repo-internal docs that must not be
published"; faststream-outbox/mkdocs.yml, modern-di/mkdocs.yml exclude /agents/ and /adr/;
lite-bootstrap/mkdocs.yml has neither key). That swap makes the situation worse, not better:
not_in_nav and exclude_docs are both unsupported, but exclude_docs failing open means unlisted
internal pages get published, not merely mis-navigated.

Next step

Do not port. Re-check when Zensical announces beta (https://zensical.org/docs/upgrade/#versioning
is where the wording will change; the newsletter and GitHub releases are the announcement channels).
Update the issue's revisit trigger to four items, in this order of severity:
- exclude_docs support — https://github.com/zensical/backlog/issues/65 (new; blocks the three sites that use it, fails silently by publishing internal docs)
- orphaned-page detection to replace validation.omitted_files — https://github.com/zensical/backlog/issues/63
- page.is_homepage (or a documented template-context reference) — affects all four overrides/main.html, not just the org
- validation.absolute_links / unrecognized_links
  Drop the not_in_nav note and the "classic variant fidelity" item; replace the latter with a
  one-line "verify by build" task, since classic is documented, recommended for migrations, and
  still actively shipped.
Cheap watch: subscribe to zensical/backlog#65 and #63 rather than re-running this survey.
Optional, low-cost hedge available today and independent of any migration: replace
page.is_homepage in the four overrides/main.html files with
page.url == nav.homepage.url, which is correct under MkDocs now and would survive a future port.

Item 4 above is now tracked separately as #71 — it is correct under MkDocs today and does not
depend on this issue.

This was generated by AI during triage.

Revisit check — 2026-09-15

Trigger has not fired. Kept enhancement + needs-triage, nothing to port.

Fact	Value	Source
Latest release	`0.0.62`, uploaded 2026-09-13	`https://pypi.org/pypi/zensical/json`
Releases since last check (0.0.59)	3: `0.0.60`, `0.0.61`, `0.0.62`	same
PyPI classifier	`Development Status :: 3 - Alpha`	same
Versioning wording	unchanged: "approaching a beta release", no date	`https://zensical.org/docs/upgrade/#versioning`
backlog#65 (`exclude_docs`)	open, no activity since 2025-11-22	`https://github.com/zensical/backlog/issues/65`
backlog#63 (orphan pages / `not_in_nav`)	open, no activity since 2025-11-20	`https://github.com/zensical/backlog/issues/63`
backlog#83 (`llmstxt`)	open, no activity since 2026-01-05	`https://github.com/zensical/backlog/issues/83`

Release notes for 0.0.60–0.0.62 cover the table-reader plugin, page and anchor redirects, mkdocs-callouts, and relaxed plugin-settings validation. None touch exclude_docs, omitted_files, absolute_links, unrecognized_links, or the template context.

Redundancy check: no zensical.toml and no Zensical reference anywhere in the org tree. Not started.

Body corrections

Blast radius has grown. Eight repos now carry a mkdocs.yml, not four: the original .github, faststream-outbox, modern-di, lite-bootstrap, plus httpware, faststream-redis-timers, semvertag, that-depends. Seven of the eight use exclude_docs (all but that-depends), and six declare a validation: block (.github and that-depends do not). Trigger items 1 and 2 therefore block seven and six repos respectively, not three.
Item 3 (page.is_homepage) is now worked around everywhere. Replace page.is_homepage with a builder-portable homepage check in every overrides/main.html #71 covered four repos on 2026-09-06; the three repos added since are fixed in httpware#126, semvertag#70 (both merged) and faststream-redis-timers#76 (open, blocked on unrelated lint drift). The underlying gap — no documented template context in Zensical — is unchanged, so the item stays on the trigger list as "re-verify nav.homepage at port time".

Next re-check when the versioning wording at https://zensical.org/docs/upgrade/#versioning changes, or backlog#65 / #63 move.

Checked 2026-10-03 against 0.0.67. Still blocked, but two things moved.

Release line: per Upcoming changes, 0.1.0 ships on 2026-11-05 and leaves the 0.0.x alpha series. 1.0 is described as a later formality, so 0.1.0 is the real revisit trigger, not "beta/1.0".
Deadline: Material for MkDocs critical maintenance is extended to 2027-05-05. That puts a date on the migration.

The four blockers:

exclude_docs: Support exclude_docs and draft_docs settings in mkdocs.yml zensical/backlog#65 is still open.
Orphaned-page detection: Support not_in_nav setting in mkdocs.yml zensical/backlog#63 is still open.
page.is_homepage: not re-checked here.
plugins.llmstxt: Support for mkdocs-llmstxt plugin functionality zensical/backlog#83 was closed as completed on 2026-10-02. Its replacement shipped in 0.0.67, so this one needs a build check, not a wait.

This was generated by AI.

Checked 2026-10-10 against Zensical 0.0.69 (released 2026-10-08): still blocked. PyPI still lists it as Development Status :: 3 - Alpha.

Of the four items in the revisit trigger:

exclude_docs (backlog#65): still open.
Orphaned-page detection (backlog#63): still open.
page.is_homepage: not re-checked.
plugins.llmstxt (backlog#83): resolved. A replacement shipped in Zensical 0.0.67 and the issue is closed. Porting modern-di's llmstxt config to it would still need a build check.

The two hardest blockers (1 and 2) remain, so nothing changes here yet.

This was generated by AI.

Checked 2026-10-24 against Zensical 0.0.72 (released 2026-10-23): still blocked. PyPI still lists Development Status :: 3 - Alpha, and 0.1.0 is still planned for 2026-11-05.

Of the four items in the revisit trigger:

exclude_docs (backlog#65): resolved. 0.0.70 added exclude_docs, draft_docs and not_in_nav, and ci: gate PRs on local links, and stop publishing the ADRs #65 is closed. This was the fail-open blocker. At port time, check by build that docs/adr/ and docs/agents/ stay out of the output.
Orphaned-page detection: still missing. backlog#63 is closed, but it was about not_in_nav, which 0.0.70 added. It was never about validation.omitted_files, so the issue body links it to the wrong thing. No 0.0.70 to 0.0.72 release note mentions validation, omitted_files, absolute_links or unrecognized_links, and no backlog issue tracks them.
page.is_homepage: not re-checked.
plugins.llmstxt: unchanged since the last check. It needs a build check, not a wait.

Item 2 is now the main gap. Without a replacement, the six repos with a validation: block lose orphaned-page checks without any warning.

Checked 2026-11-04: the release gate has not fired.

Latest Zensical is 0.0.74, still classified Alpha. The upstream announcement still schedules 0.1.0 for November 5, 2026. Recheck after that release, then verify validation parity, excluded directories and theme fidelity by building before proceeding with migration.

Navigation Menu

Repository navigation

Evaluate Zensical Beta migration: validation and template blockers #60

Goal and current status

Verified build findings

Remaining blockers and completion checks

1. Preserve validation behavior, or explicitly decide what loss is acceptable

2. Make template overrides compatible

3. Verify llmstxt content parity

4. Verify classic visual and deployment behavior

Reproduction

Triage Notes

Revisit check — 2026-09-06

Trigger status

Delta since 2026-07-05 that matters to us

Blocker 1 — `page.is_homepage` in custom templates

Supported way to special-case the home page today

Blast radius, corrected

Blocker 2 — validation parity

What `faststream-outbox` actually depends on

Blocker 3 — `classic` variant fidelity

Config-surface gap check

Next step

Revisit check — 2026-09-15

Body corrections

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Evaluate Zensical Beta migration: validation and template blockers #60

Description

Goal and current status

Verified build findings

Remaining blockers and completion checks

1. Preserve validation behavior, or explicitly decide what loss is acceptable

2. Make template overrides compatible

3. Verify llmstxt content parity

4. Verify classic visual and deployment behavior

Reproduction

Activity

lesnik512 commented on Sep 6, 2026

Triage Notes

lesnik512 commented on Sep 6, 2026

Revisit check — 2026-09-06

Trigger status

Delta since 2026-07-05 that matters to us

Blocker 1 — page.is_homepage in custom templates

Supported way to special-case the home page today

Blast radius, corrected

Blocker 2 — validation parity

What faststream-outbox actually depends on

Blocker 3 — classic variant fidelity

Config-surface gap check

Next step

lesnik512 commented on Sep 15, 2026

Revisit check — 2026-09-15

Body corrections

lesnik512 commented on Oct 3, 2026

lesnik512 commented on Oct 10, 2026

lesnik512 commented on Oct 24, 2026

lesnik512 commented on Nov 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Blocker 1 — `page.is_homepage` in custom templates

What `faststream-outbox` actually depends on

Blocker 3 — `classic` variant fidelity