Skip to content

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

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#170
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 9 pages — including
index.html's <title>, og:title and twitter:title, which are what this touches.

@lesnik512
lesnik512 merged commit 04bec8b into main Sep 6, 2026
11 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