DOC-7104: Migrate content/operate/rs/7.22/references/ (incl. rest-api) to render hooks - #4093
Merged
Merged
Conversation
…) to render hooks
Unit 8 of 15: converts the frozen 7.22 references tree (272 files, 189
carrying relref/callout shortcodes) from {{< relref >}} and
{{< note >}}/{{< warning >}} shortcodes to plain markdown links and
> [!NOTE]/> [!WARNING] blockquotes resolved by the DOC-6909 render hooks.
Unlike unit 6 (live tree), this unit's rest-api/ subtree is in scope per
Andy's explicit decision to include all frozen-version content.
Real counts (re-measured by grep, not taken from the ticket estimate):
1176 relref shortcodes, 29 callouts (19 note, 10 warning) across 189 files.
Post-conversion grep confirms 0 remaining shortcode-form instances and
1176+29 in the new forms.
One gotcha instance found and hand-fixed: cli-utilities/rladmin/_index.md
had a {{<note>}} indented inside a numbered list item, with only the
header line indented and the continuation/closing lines flush left (the
known converter limitation). Fixed by re-indenting all blockquote lines to
match the list item and dropping the stray blank `>` artifact line;
verified via rendered HTML that the <li> nesting is unchanged before/after.
No relref-missing-slash or missing-paren instances found in this unit.
Verification: full-site hugo builds before/after (non-minified -- see
below), diffed with the DOC-7104-diff-hrefs-fix build/diff_rendered_hrefs.py
scoped to operate/rs/7.22/references: 270/270 pages compared, 0 href-set
changes.
Build note: `hugo --minify` currently fails site-wide on this checkout with
an unrelated, pre-existing esbuild syntax error while minifying a script on
/commands/cf.reserve (nothing under this unit's path). Confirmed
pre-existing on unmigrated content too, so it isn't something introduced
here. Verification builds therefore ran without --minify; both before and
after used identical flags, and rendered hrefs are unaffected by
minification, so the comparison is still valid. Flagging so the underlying
build issue can be tracked separately.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
Contributor
🧠 Redis MemoryFound 9 related items from repository history:
Memory updated at d86d278 |
Contributor
3 tasks
5 tasks
This was referenced Sep 23, 2026
andy-stark-redis
requested review from
dwdougherty
and removed request for
kaitlynmichael
September 23, 2026 15:19
dwdougherty
requested changes
Sep 23, 2026
dwdougherty
left a comment
dwdougherty
left a comment
Collaborator
There was a problem hiding this comment.
A few issues with this one.
| --- | ||
|
|
||
| The following tables show which Redis Open Source [server management commands]({{< relref "/commands" >}}?group=server) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. | ||
| The following tables show which Redis Open Source [server management commands](/commands?group=server) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The following tables show which Redis Open Source [server management commands](/commands?group=server) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. | |
| The following tables show which Redis Open Source [server management commands](/content/commands?group=server) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. |
| --- | ||
|
|
||
| The following table shows which Redis Open Source [transaction commands]({{< relref "/commands" >}}?group=transactions) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. | ||
| The following table shows which Redis Open Source [transaction commands](/commands?group=transactions) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The following table shows which Redis Open Source [transaction commands](/commands?group=transactions) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. | |
| The following table shows which Redis Open Source [transaction commands](/content/commands?group=transactions) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. |
| | Method | Path | Description | | ||
| |--------|------|-------------| | ||
| | [PUT]({{< relref "./backup_reset_status#put-bdbs-actions-backup-reset-status" >}}) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status | | ||
| | [PUT](./backup_reset_status#put-bdbs-actions-backup-reset-status) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status | |
Collaborator
There was a problem hiding this comment.
Lots of bad links in this file.
Comment on lines
+25
to
+26
| | [GET](./all#get-all-debuginfo) | `/v1/debuginfo/all` | Gets debug info for all nodes | | ||
| | [GET](./all/bdb#get-all-debuginfo-bdb) | `/v1/debuginfo/all/bdb/{bdb_uid}` | Gets debug info for a database from all nodes | |
Comment on lines
+32
to
+33
| | [GET](./node#get-debuginfo-node) | `/v1/debuginfo/node` | Gets debug info for the current node | | ||
| | [GET](./node/bdb#get-debuginfo-node-bdb) | `/v1/debuginfo/node/bdb/{bdb_uid}` | Gets debug info for a database from the current node | |
…filenames in relative refs
Two issues human review flagged:
1. Two `/commands?group=<x>` links (from `{{< relref "/commands" >}}
?group=<x>`) were left in bare form instead of the migration's
canonical /content/ prefix. Fixed those 2 plus 5 more of the identical
shape in the same directory (compatibility/commands/{cluster,
connection,generic,pub-sub,scripting}.md) that weren't individually
flagged but share the pattern. Confirmed via rendered HTML that
/commands?group=x and /content/commands?group=x resolve to the exact
same href (render-link.html strips the /content prefix before its own
GetPage lookup, so both forms produce an identical final path) --
this is a portability/consistency fix, not a functional one.
2. Several source-relative relrefs (`./all#anchor`, `./node/bdb#anchor`,
etc.) pointed at a directory or file with no extension. Hugo's
render-link.html resolves these correctly on the live site (GetPage's
page-relative lookup finds the section/leaf either way -- confirmed
byte-identical rendered hrefs before/after), but a path with no
extension isn't a working link when the same markdown renders in
GitHub's PR view or VS Code, which is exactly the portability this
migration is meant to preserve. Fixed by pointing each at its real
filename (`./all/_index.md#anchor`, `./all/bdb.md#anchor`, etc.) in
the 2 files review flagged (bdbs/actions/_index.md, debuginfo/_index.md,
10 links total) -- confirmed no other file in this unit's scope
carries the same pattern.
Verified via build/diff_rendered_hrefs.py: 0 href diffs across all 446
pages in this unit.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
andy-stark-redis
added a commit
that referenced
this pull request
Sep 24, 2026
…(same fix as #4093 review) Same defect pattern found and fixed on PR #4093 (7.22/references) after human review: 7 bare /commands?group=<x> links in compatibility/commands/ missing the /content/ prefix, and 10 source-relative relrefs in rest-api/requests/{bdbs/actions,debuginfo}/_index.md pointing at a directory/file with no extension (works via Hugo's render-link.html GetPage resolution, confirmed byte-identical rendered href before/after, but not a working link when the same markdown renders in GitHub's PR view or VS Code). This version snapshot is a near-identical copy of 7.22's rest-api tree, so the same instances recur in the same two files. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
andy-stark-redis
added a commit
that referenced
this pull request
Sep 24, 2026
…(same fix as #4093 review) Same defect pattern found and fixed on PR #4093 (7.22/references) after human review: 7 bare /commands?group=<x> links in compatibility/commands/ missing the /content/ prefix, and 10 source-relative relrefs in rest-api/requests/{bdbs/actions,debuginfo}/_index.md pointing at a directory/file with no extension (works via Hugo's render-link.html GetPage resolution, confirmed byte-identical rendered href before/after, but not a working link when the same markdown renders in GitHub's PR view or VS Code). This version snapshot is a near-identical copy of 7.22's rest-api tree, so the same instances recur in the same two files. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
andy-stark-redis
added a commit
that referenced
this pull request
Sep 24, 2026
…(same fix as #4093 review) Same defect pattern found and fixed on PR #4093 (7.22/references) after human review: 7 bare /commands?group=<x> links in compatibility/commands/ missing the /content/ prefix, and 10 source-relative relrefs in rest-api/requests/{bdbs/actions,debuginfo}/_index.md pointing at a directory/file with no extension (works via Hugo's render-link.html GetPage resolution, confirmed byte-identical rendered href before/after, but not a working link when the same markdown renders in GitHub's PR view or VS Code). This version snapshot is a near-identical copy of 7.22's rest-api tree, so the same instances recur in the same two files. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
Author
|
Fixed both issues:
Verified via |
andy-stark-redis
added a commit
that referenced
this pull request
Sep 24, 2026
…o slash The original regex required `/` or end-of-string right after the mount name, so a link like `/commands?group=cluster` (no trailing slash before the query) silently passed through unchecked -- this tool's own blind spot, found the hard way: human review caught it by hand on DOC-7104 PR #4093, and the identical instances recurred in #4094/#4096/#4098 before this fix existed to catch them. Also reconsiders the `/commands` special case: it has no backing _index.md on disk, so _find_content_file always reports it unresolvable, but Hugo auto-generates a section page for the directory and GetPage finds it anyway (confirmed by building both /commands?group=x and /content/commands?group=x and comparing rendered hrefs -- identical). Review wanted the canonical form applied there too, so it's now hardcoded as FIXABLE instead of silently skipped. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…w pattern as #4094) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
6 tasks
1 task
Contributor
Author
|
Also fixed the bare |
andy-stark-redis
added a commit
that referenced
this pull request
Sep 24, 2026
…er hooks Converts relref link shortcodes and note/tip/warning/alert callout shortcodes to render-hook equivalents across content/operate/rs/7.22/, excluding references/ (done separately in #4093) -- 157 of 174 files, 1,135 relref links and 157 callouts. Found and fixed 40 callout instances across 26 files nested inside list items, where the migration script drops indentation on a blockquote's continuation/closing lines. One pre-existing missing-paren relref fixed in databases/connect/troubleshooting-guide.md (the HGETALL link). Review (round 2) caught three more issues, all fixed: - Bare /commands links in _index.md and security/access-control/redis-acl-overview.md missing the /content/ prefix used everywhere else in this migration -- confirmed via rendered HTML that both forms produce an identical href. - new-features-redis-enterprise.md: applied the same /content/ prefix to the 6 known pre-existing dead relref targets in this draft: true page, for consistency. Cosmetic only -- none of the 6 targets exist regardless of prefix. - databases/import-export/flush.md: the port-configurations link's anchor was a stray old absolute URL concatenated into the fragment, present in the source relref shortcode before this migration touched it. Replaced with the real heading slug from this version's own port-configurations.md. Verified via build/diff_rendered_hrefs.py: after filtering the known CSS-asset-fingerprint noise from comparing builds in two different worktree environments, the only real content change is the corrected flush.md anchor -- everything else confirmed 0 diff. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
andy-stark-redis
added a commit
that referenced
this pull request
Sep 24, 2026
migrate_shortcode_links.py's linkify stage correctly canonicalizes almost every converted link to /content/<path>.md[#anchor], but a link that gets a manual post-hoc text fix after the pipeline already ran (e.g. inserting a separator slash a relref-plus-literal-suffix concatenation was missing) never gets a second pass through linkify. The result is a bare /operate/... path that resolves to the exact same rendered href as the canonical form, so build/diff_rendered_hrefs.py -- this migration's usual verification -- is blind to it by construction. Found on PR #4086 (release-notes/ unit): human review manually flagged 8 malformed links; a corpus-wide grep for the same shape found 21 across 9 files (13 more than manual review caught), plus 8 more that turned out to be genuinely pre-existing dead links in the identical shape, invisible to any prior check since Hugo's relref shortcode only ever validated its own target, never text concatenated onto it afterward. check_uncanonicalized_links.py reuses migrate_shortcode_links.py's own resolver (_find_content_file) so a --fix run applies the exact same rewrite the pipeline would have. Three outcomes: FIXABLE (resolves, --fix rewrites it), MOUNT_ONLY (resolves only through a Hugo module mount -- never auto-fixed, same rationale _find_content_file already documents for not following mounts on a rewrite), DEAD (doesn't resolve at all -- reported only, never guessed). A second commit fixed the tool's own blind spot, found immediately on its first real use: the original MOUNT_PREFIX_RX required a `/` or end-of-string right after the mount name, so a bare `?query`/`#fragment` with no slash before it (e.g. /commands?group=x) silently passed through unchecked -- exactly the shape human review caught by hand across DOC-7104 PR #4093/#4094/#4096/#4098. Also reconsidered the `/commands` special case: it has no backing _index.md on disk so the filesystem resolver always calls it unresolvable, but Hugo auto-generates a section page for the directory and GetPage finds it anyway (confirmed by building both /commands?group=x and /content/commands?group=x and diffing rendered hrefs -- identical). Now hardcoded as FIXABLE instead of silently skipped. Verified against the pre-fix state of PR #4086: reproduces the exact 21 FIXABLE / 8 DEAD split. A full-corpus scan of content/ elsewhere comes back to 3 unrelated hits, confirming it isn't noisy. 8 unit tests cover both commits' behavior. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
dwdougherty
approved these changes
Sep 24, 2026
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
2 participants
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.
Summary
Unit 8 of 15 in the DOC-7104 shortcode-to-render-hook migration (extending DOC-6909 into
content/operate/rs/). This is the first of 8 units covering frozen version snapshots: converts every file undercontent/operate/rs/7.22/references/, includingreferences/rest-api/(in scope for this ticket, unlike unit 6's live-tree exclusion), per Andy's explicit decision that all frozen-version content is in scope.{{< relref "..." >}}→ plain markdown links resolved byrender-link.html{{< note >}}/{{< warning >}}→> [!NOTE]/> [!WARNING]blockquotes resolved byrender-blockquote.htmlcontent/operate/rs/AGENTS.md, this frozen tree still says "Redis Enterprise Software" deliberately).My own counts (re-measured by grep, not the ticket's estimate)
.mdfiles undercontent/operate/rs/7.22/references/(190 of them underrest-api/){{< relref >}}shortcodes → 1176 plain linksnote, 10warning)[!NOTE]/[!WARNING]blockquotes presentGotchas checked
cli-utilities/rladmin/_index.md— a{{<note>}}nested inside a numbered step, where the converter only indented the header line, leaving continuation/closing lines flush left plus a stray blank>artifact. Hand-fixed by re-indenting all blockquote lines to match the list item's nesting and removing the artifact line. Verified via rendered HTML that<li>nesting is identical before/after.?group=pattern present in 7 compatibility/commands pages is the already-handled house-style case (relref's own doc says this is expected), not this gotcha.](relref...)pattern.Build note
hugo --minifycurrently fails site-wide on this checkout with a pre-existing, unrelated esbuild syntax error minifying an inline script on/commands/cf.reserve(confirmed present before any change in this PR, on unmigrated content). Verification builds (before/after) therefore both ran without--minify, using identical flags on both sides — renderedhrefvalues aren't affected by minification, so the href-diff comparison is still valid. Flagging this separately since it blocks the standard--minifyrecipe for every unit until fixed.Test plan
find content/operate/rs/7.22/references -name '*.md' | wc -l→ 272 (190 underrest-api/)build/diff_rendered_hrefs.py(patched version from DOC-7104: Fix diff_rendered_hrefs.py to catch unquoted href attributes #4087, used for verification only, not included in this diff) scoped tooperate/rs/7.22/references: 270/270 pages compared, 0 href-set changesbuild/diff_rendered_hrefs.pyis not part of this PR's diff<li>nesting matches before/after🤖 Generated with Claude Code
Note
Low Risk
Documentation-only syntax migration with no product or API behavior changes; main risk is broken links if path resolution differs from former relref behavior.
Overview
This PR mechanically migrates the frozen
content/operate/rs/7.22/references/tree (includingrest-api/) from Hugo shortcodes to markdown that render hooks resolve—part of the broader DOC-7104 shortcode-to-hook work.{{< relref "..." >}}links become plain markdown paths under/content/...(for example CLI utilities, compatibility command tables, REST API cross-links).{{< note >}}/{{< warning >}}become GitHub-style> [!NOTE]/> [!WARNING]blockquotes. Wording and technical content are unchanged.Scope is broad across cli-utilities (
crdb-cli,redis-cli,rladmin), compatibility pages, and REST API index material—hundreds of link substitutions plus a small number of callout conversions.Reviewed by Cursor Bugbot for commit d86d278. Bugbot is set up for automated code reviews on this repo. Configure here.