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

High Risk
The link hook is global and reprocesses every existing plain Markdown link on build; regressions in resolution, warnings, or malformed-URL handling can break the site build or silently change hrefs across ~31k links.

Overview
Introduces Hugo markup render hooks so docs can move off relref and callout shortcodes toward portable Markdown, and documents the full migration strategy in HUGO_DEPENDENCY_ASSESSMENT.md. No content/ changes in this PR—relref and plain links coexist during rollout.

The render-link hook resolves internal Markdown links to published permalinks (parity-tested against relref), normalises existing plain links site-wide, and includes corpus-scale safeguards: a relref placeholder guard, external detection via findRE (not urls.Parse), .PageInner resolution for mounts/transclusion, first-#-only anchor splitting with safeURL, and page-bundle resource fallback before warnings.

The render-blockquote hook maps > [!NOTE] / > [!WARNING] (etc.) to the same alert UI as today’s shortcodes while leaving normal blockquotes unchanged; alert bodies render as native Markdown so links inside callouts get correct page context (unlike markdownify in shortcodes).

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

[github-actions]

DOC-6909

[github-actions]

🧠 Redis Memory

Found 8 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

Memory updated at 224e895