chore(docs): use a builder-portable homepage check in the override template - #170
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
page.is_homepageis a MkDocsPageproperty with no equivalent in Zensical, which the org isevaluating 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:titlewith no warning.nav.homepageis exposed by both builders — MkDocs documents it ashomepage: Page | None(https://www.mkdocs.org/dev-guide/themes/), and Zensical serializes it in
crates/zensical/src/structure/nav/view.rs— so comparingpage.urlagainst 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 %}, thennot is_homewherenot page.is_homepageused to be.nav.homepage andguard is load-bearing: MkDocs types itPage | None. When it isNonethe expression is falsy, which matches
is_homepagebeingFalseon every page of a site withno home page.
{%-left-trim is also load-bearing: without it the new tag adds a blank line to everyrendered 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 thatwork landing.
Verification
Full-site build diff with the pinned toolchain,
mainvs this branch:--strictpasses on both, and the output is byte-identical across all 9 pages — includingindex.html's<title>,og:titleandtwitter:title, which are what this touches.