Skip to content

chore(docs): use a builder-portable homepage check in the override template - #167

Merged
lesnik512 merged 1 commit into
mainfrom
chore/portable-homepage-check
Sep 6, 2026
Merged

chore(docs): use a builder-portable homepage check in the override template#167
lesnik512 merged 1 commit into
mainfrom
chore/portable-homepage-check

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Why

page.is_homepage is a MkDocs Page property with no equivalent in Zensical, which the org is
evaluating as a future docs builder (modern-python/.github#60). It fails silently, not loudly:
at Zensical 0.0.59 the property does not exist anywhere in the source, and an undefined name
resolves falsy in MiniJinja — so the home page would fall through to the non-home branch and emit a
wrong og:title / twitter:title with no warning.

nav.homepage is exposed by both builders — MkDocs documents it as homepage: Page | None
(https://www.mkdocs.org/dev-guide/themes/), and Zensical serializes it in
crates/zensical/src/structure/nav/view.rs — so comparing page.url against it is portable.

Part of modern-python/.github#71, which makes the same change in each repo with an
overrides/main.html.

Design

{%- set is_home = nav.homepage and page.url == nav.homepage.url %}, then not is_home where
not page.is_homepage used to be.

  • The nav.homepage and guard is load-bearing: MkDocs types it Page | None. When it is None
    the expression is falsy, which matches is_homepage being False on every page of a site with
    no home page.
  • The {%- left-trim is also load-bearing: without it the new tag adds a blank line to every
    rendered page.

Non-goals

Not a Zensical migration. #60 stays open and stays blocked on unrelated gaps (exclude_docs,
validation.omitted_files). This change is a no-op under MkDocs today and does not depend on that
work landing.

Verification

Full-site build diff with the pinned toolchain, main vs this branch:

uvx --with-requirements docs/requirements.txt mkdocs build --strict -d <dir>
diff -r <before> <after>

--strict passes on both, and the output is byte-identical across all 24 pages — including
index.html's <title>, og:title and twitter:title, which are what this touches.

@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown

Benchmark gate

✅ gate passed

scenario msg/s delete/msg WALrec/msg WALB/msg fpi upd del dead_tup
consumer/w1/b10 926 1.000 6.80 913 242 5000 5000 10000
consumer/w1/b100 947 1.000 6.84 919 243 5000 5000 10000
consumer/w2/b10 1125 1.000 6.79 959 242 5000 5000 10000
consumer/w2/b100 1340 1.000 6.73 956 243 5000 5000 10000
consumer/w4/b10 1040 1.000 6.79 981 261 5000 5000 10000
consumer/w4/b100 1533 1.000 6.85 1033 244 5000 5000 10000
consumer/w1/b100/tfbs100 5484 0.010 6.07 1116 243 5000 5000 10000
producer/w1/b100 2215 0.000 3.04 584 0 0 0 0

Gated (fails the build): delete_calls + tuple counters (upd/del/ins) + the producer's insert_calls, exact; select_calls within +2; wal_records within a 10% band. msg/s, WAL bytes and total calls are informational (timing/FPI noise).

@lesnik512
lesnik512 force-pushed the chore/portable-homepage-check branch from 9571ce6 to 73ec1b6 Compare September 6, 2026 17:46
@lesnik512

Copy link
Copy Markdown
Member Author

Force-pushed after a rebase onto main. The branch had been cut from a HEAD that already carried docs: drop the local PR template, inheriting the org default, so it was carrying a superseded draft of a change that has since merged to main in its final form. That commit is dropped; the branch is now main plus the single overrides/main.html commit. Re-verified against the new main: mkdocs build --strict on both sides, output diffed recursively, identical.

@lesnik512
lesnik512 merged commit 3e952cd into main Sep 6, 2026
9 checks passed
@lesnik512
lesnik512 deleted the chore/portable-homepage-check branch September 6, 2026 18:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant