Skip to content

fix: resolve page lookups in foreign render contexts#317

Merged
markdumay merged 3 commits into
mainfrom
develop
May 25, 2026
Merged

fix: resolve page lookups in foreign render contexts#317
markdumay merged 3 commits into
mainfrom
develop

Conversation

@markdumay

Copy link
Copy Markdown
Collaborator

Summary

Two related fixes to mod-utils' page-resolution helpers, plus the 9 dependabot/chore commits already accumulated on develop.

The new fixes

  • 7b96dc3 fix(GetPage): fall back to site.GetPage for foreign-render contexts.
  • bd6b66e fix(GetStaticURL): pin the base URL to the HTML home permalink (not site.Home.RelPermalink, which returns the active output's permalink).

Why

When a Hugo layout renders content from a foreign page context — e.g. a custom output format whose layout iterates site.RegularPages and reads .Plain / .Content / .Summary of other pages — Hugo's page global is the driving page, not the page whose content is being processed.

  • Page.GetPage(url) for a relative reference uses Hugo's active rendering context (the page global), not the receiver page, so the receiver-based lookup returns nil even when $page is correctly passed. The first fix adds site.GetPage as a context-independent fallback.
  • GetStaticURL builds a base URL from site.Home.RelPermalink. During a non-HTML output render this returns the active output's permalink (e.g. /flexsearch-index.json), producing absurd patterns like /flexsearch-index.json/introduction/ that match no page in the existing where site.AllPages "RelPermalink" "like" … fallback. The second fix pins the base to the HTML home permalink, which is stable across render contexts.

The bug was surfaced by gethinode/mod-flexsearch's new lazyLoad feature (a searchindex output format that iterates all pages to build the index data). It manifests as partial [assets/link.html] - Invalid arguments / Cannot find page or asset: '<name>' errors on any consuming site with markdown links that use short page names ([text](introduction)), because the relative-name resolution chain breaks.

Verification

  • mod-utils exampleSite build clean (npm test).
  • End-to-end on gethinode.com (which had 47 errors before): patched vendored mod-utils with these fixes + removed a temporary link.html override → npm run build --ignore-scripts produces 0 errors, exit 0, flexsearch-index.json (120 docs) emitted, data-search-index=/flexsearch-index.json wired, core bundle carries the lazy runtime.
  • Reviewer smoke-test: any consuming site that uses a custom output format reading other pages' content (RSS variants, mod-flexsearch with lazyLoad=true, mod-llm's llmstxt) should now resolve short-name links correctly without link.html errors.

Coordination

  • Without these fixes, mod-flexsearch v4.3.0's lazyLoad (gethinode/mod-flexsearch@caaa1fb) produces noisy "Cannot find page or asset" errors on Hinode-docs-heavy sites — exit non-zero, even though the rendered output is correct.
  • After this releases, sites using lazy loading should bump mod-utils/v5 to the new version.

🤖 Generated with Claude Code

markdumay and others added 3 commits May 25, 2026 11:43
Page.GetPage resolves relative references against Hugo's active
rendering context (the `page` global), not the receiver page. When
content is processed from a foreign render — for example a custom
output format whose layout iterates other pages and reads .Plain,
.Content, or .Summary — the active context is the driving page, and
the receiver-based lookup returns nil even though the explicitly
passed `$page` is correct.

site.GetPage is context-independent and resolves the reference by
name across the site. Adding it as a fallback before the existing
AllPages-regex fallback fixes the lookup in foreign render contexts
without affecting normal page rendering.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
site.Home.RelPermalink returns the active output's permalink, so during
a non-HTML output render (custom searchindex / RSS / custom JSON output)
this helper would inject that output's path into the base URL and emit
nonsensical results — for example "/flexsearch-index.json/introduction"
when called from inside a searchindex output layout.

The HTML output's permalink is the canonical site root and remains
stable across render contexts; falling back to site.Home.RelPermalink
only when the html output format is absent preserves the previous
behavior for sites that disable HTML output.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@markdumay markdumay enabled auto-merge May 25, 2026 09:47
@markdumay markdumay merged commit c1af3ce into main May 25, 2026
11 checks passed
@markdumay

Copy link
Copy Markdown
Collaborator Author

🎉 This PR is included in version 5.23.2 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant