Skip to content

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

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#76
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 this org is
evaluating as a future docs builder (#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. Here that means a doubled
<title> ("Modern Python - Modern Python", the exact bug the comment in this file describes) plus 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. Comparing page.url against it is portable.

Part of #71. The sibling PRs are modern-python/faststream-outbox#167,
modern-python/modern-di#455 and modern-python/lite-bootstrap#170.

Design

{%- set is_home = nav.homepage and page.url == nav.homepage.url %} once per block, then is_home
where page.is_homepage used to be. Both blocks need their own set; Jinja block scopes do not
share it.

  • The nav.homepage and guard is load-bearing: MkDocs types it Page | None. When it is None the
    expression is falsy, matching 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.

The explanatory comment above htmltitle still describes the situation accurately and is unchanged.

Non-goals

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

Verification

uv run mkdocs build --strict on main and on this branch, output diffed recursively: identical.

This site is a single page, so that diff alone would only exercise the homepage branch. I added a
temporary second page for the comparison and confirmed both branches match:

main this branch
home <title> Modern Python Modern Python
non-home <title> Scratch Verify Page - Modern Python Scratch Verify Page - Modern Python
non-home og:title Scratch Verify Page · Modern Python Scratch Verify Page · Modern Python

The temporary page is not part of this diff.

@lesnik512
lesnik512 merged commit 634840a into main Sep 6, 2026
3 checks passed
@lesnik512
lesnik512 deleted the chore/portable-homepage-check branch September 6, 2026 17:51
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