DOC-6909 Add link and blockquote render hooks to replace relref

[andy-stark-redis]

Part 3 of 4. Stack: #3795 → #3796 → #3797 (this) → #3798

What this is

The two render hooks the investigation set out to evaluate, plus HUGO_DEPENDENCY_ASSESSMENT.md recording the evidence. No content is migrated here — relref and plain Markdown links coexist, so no page's authoring changes.

Why this is the risky one

Installing the link hook is the atomic event, not the content conversion. The hook is global and reprocesses every pre-existing plain link on the site (~31k), applying benign normalisation. That's why it lands as its own reviewable change.

Load-bearing details

Each of these was established by a corpus-scale failure, and quietly removing any of them will break something:

• Placeholder guard — goldmark runs before shortcode substitution, so an un-migrated relref is still a HAHAHUGOSHORTCODE placeholder at hook time. Without the guard, ~26,800 spurious "unresolved" warnings bury the real ones. Remove it only once relref is gone.
• findRE not urls.Parse for external detection — urls.Parse hard-errors on malformed destinations and fails the entire build.
• .PageInner so transcluded content resolves against the page whose Markdown holds the link.
• First-#-only anchor split, and safeURL on the composed href or Go emits ZgotmplZ. Hugo has no strings.Index.
• Page-bundle resource fallback before warning, for the companion source files the use-case demos link.

The blockquote hook reproduces existing callout styling for native > [!NOTE] syntax and leaves ordinary blockquotes byte-identical to Hugo's default. It's a prerequisite for relative links inside callouts, because the callout shortcodes render inner content through markdownify, which has no page context.

Known: one warning on current main

0.24.0 and 0.25.0 of the synced RedisVL docs use a relative mcp.md#… link on pages that render via markdownify, so the hook resolves them against the site root and warns. The target file exists — this is not a dead link, it's the markdownify context problem. The older copies were fixed with relref in #3795; the durable fix is in build/redisvl_docs_sync.py.

---

Note

Medium Risk
The link hook is a global build-time change that reprocesses ~31k existing plain links and can surface build warnings or failures on malformed links; behavior is documented but regressions would affect all pages.

Overview
Adds global Hugo render hooks so plain Markdown can eventually replace relref and callout shortcodes, plus HUGO_DEPENDENCY_ASSESSMENT.md capturing corpus-scale parity testing and a phased migration plan. No content/ changes in this PR—relref and plain links coexist.

The link hook (render-link.html) resolves internal Markdown links to published permalinks (including mounts via .PageInner), normalises existing plain links site-wide, warns on unresolved targets, and includes transition guards for unexpanded shortcode placeholders, external URL detection without urls.Parse, page-bundle resources, and anchor handling.

The blockquote hook maps > [!NOTE]-style alerts to existing callout styling while leaving normal blockquotes unchanged—enabling page-context link resolution inside callouts vs shortcode markdownify.

^{Reviewed by Cursor Bugbot for commit e484110. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

DOC-6909

[github-actions]

🧠 Redis Memory

Found 9 related items from repository history:

• Commit — DOC-6909 Add link render hook to replace relref, with coexistence findings

  DOC-6909 Add link render hook to replace relref, with coexistence findings

• PR — DOC-6909 Add link render hook to replace relref (investigation)

  Note: implementing this revealed some existing problems that needed fixing before adding the new render hook stuff. The "interesting" stuff

• Commit — DOC-6909 Add blockquote-alert render hook (portable callouts)

  DOC-6909 Add blockquote-alert render hook (portable callouts)

• PR — DOC-6909 Migrate develop/clients/redis-py to portable Markdown links and callouts

  Converts one section end to end as the investigation's proof: 147 links to

• PR — DOC-6909 Teach the feed pipeline and version archiver the /content/ link form

  Prepares the two tools that read relref as a literal string, ahead of any

• Commit — DOC-6909 Add link and blockquote render hooks to replace relref

  DOC-6909 Add link and blockquote render hooks to replace relref

• Commit — DOC-6909 Add link and blockquote render hooks to replace relref

  DOC-6909 Add link and blockquote render hooks to replace relref

• Commit — DOC-6909 Add link and blockquote render hooks to replace relref

  DOC-6909 Add link and blockquote render hooks to replace relref

• Commit — DOC-6909 Add link and blockquote render hooks to replace relref

  DOC-6909 Add link and blockquote render hooks to replace relref

Memory updated at e484110