chore(docs): use a builder-portable homepage check in the override template - #76
Merged
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 this org isevaluating 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 awrong
og:title/twitter:title, with 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. Comparingpage.urlagainst 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, thenis_homewhere
page.is_homepageused to be. Both blocks need their ownset; Jinja block scopes do notshare it.
nav.homepage andguard is load-bearing: MkDocs types itPage | None. When it isNonetheexpression is falsy, matching
is_homepagebeingFalseon every page of a site with no homepage.
{%-left-trim is also load-bearing: without it the new tag adds a blank line to everyrendered page.
The explanatory comment above
htmltitlestill describes the situation accurately and is unchanged.Non-goals
Not a Zensical migration. #60 stays open and stays blocked on
exclude_docsandvalidation.omitted_files. This is a no-op under MkDocs today and does not depend on that work.Verification
uv run mkdocs build --strictonmainand 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<title>Modern PythonModern Python<title>Scratch Verify Page - Modern PythonScratch Verify Page - Modern Pythonog:titleScratch Verify Page · Modern PythonScratch Verify Page · Modern PythonThe temporary page is not part of this diff.