DOC-7104: Migrate content/operate/rs/8.0/references/ (incl. rest-api) to render hooks by andy-stark-redis · Pull Request #4098 · redis/docs

andy-stark-redis · 2026-09-23T13:52:50Z

Summary

Unit 14 of 15 in the DOC-7104 shortcode-to-render-hook migration: converts the frozen content/operate/rs/8.0/references/ tree (283 files) from {{< relref >}} and {{< note >}}/{{< warning >}} shortcodes to plain Markdown links and > [!NOTE]/> [!WARNING] blockquotes, resolved by the DOC-6909 render hooks (layouts/_default/_markup/render-link.html, layouts/_default/_markup/render-blockquote.html).

The rest-api/ subtree (199 of the 283 files) is explicitly in scope per the ticket: it was generated once when 8.0 was frozen and is never regenerated, so a one-time mechanical conversion is safe and permanent.

193 of 283 files changed (had a relref or callout to convert)
Real counts, re-measured by grep against the pre-conversion tree: 1265 relref shortcodes (1132 {{< relref, 133 no-space {{<relref) across 191 files; 25 callout shortcodes (18 note, 7 warning, 0 tip/alert) across 20 files (18 files carry both)
Post-conversion grep confirms 0 remaining shortcode-form relref/callout instances in the tree
Purely mechanical — no prose, terminology, or fact changes

Findings

One gotcha found and hand-fixed: cli-utilities/rladmin/_index.md had a {{<note>}} indented inside a numbered list item. The converter only indented the header line, leaving the continuation/closing lines flush left plus a stray whitespace-only > artifact — the same defect pattern already fixed in the 7.4, 7.22, and 7.8 units, recurring here a 4th time as predicted. Fixed by re-indenting all blockquote lines to match the list item and dropping the stray line. Checked the other 19 callout-bearing files; none are indented inside a list.
cli-utilities/redis-cli/_index.md's relrefs were all well-formed — unlike 7.22/7.4, this snapshot (like 7.8) has no missing-paren instance.
No relref-missing-slash instances found anywhere in this unit.

Verification

Full-site Hugo builds before/after (non-minified — the cf.reserve esbuild minify bug and the develop/clients jupyter-example error are both pre-existing and unrelated to this unit's path)
Diffed with the patched build/diff_rendered_hrefs.py (from branch DOC-7104-diff-hrefs-fix, PR DOC-7104: Fix diff_rendered_hrefs.py to catch unquoted href attributes #4087, not yet merged — staged for verification only and reverted before this commit) scoped to operate/rs/8.0/references: 281/281 pages compared, 0 href-set changes
build/diff_rendered_hrefs.py carries no changes in this PR

Test plan

find content/operate/rs/8.0/references -name '*.md' confirms 283 files including rest-api/
Pre-flight grep counts re-measured directly (not taken from ticket estimate)
build/migrate_shortcode_links.py all run over the full file list; 193/283 files changed
Hand-fixed the recurring rladmin/_index.md indentation gotcha; verified no other indented callouts in the tree
Before/after full-site Hugo builds (no --minify, foreground, blocking)
diff_rendered_hrefs.py scoped to operate/rs/8.0/references: 0 href diffs
Confirmed build/diff_rendered_hrefs.py is not part of this diff

🤖 Generated with Claude Code

Note

Low Risk
Documentation-only mechanical link and callout syntax changes with verified href parity; no product or runtime behavior changes.

Overview
This PR mechanically migrates the frozen content/operate/rs/8.0/references/ tree (including rest-api/) from Hugo {{< relref >}} internal links and {{< note >}} / {{< warning >}} shortcodes to plain Markdown: /content/... link targets and > [!NOTE] / > [!WARNING] blockquotes, so DOC-6909 render hooks can resolve links and callouts at build time.

The edits span alerts, CLI reference (crdb-cli, rladmin, redis-cli), compatibility command tables, memtier benchmark, and REST API object docs—link destinations and wording are unchanged; only syntax moves off shortcodes. One hand fix aligns an indented NOTE inside a numbered list in rladmin/_index.md (same pattern as earlier 7.x units).

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

… to render hooks Unit 14 of 15: converts the frozen 8.0 references tree (283 files, 193 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. The rest-api/ subtree (199 of the 283 files) is explicitly in scope per the ticket: it was generated once when 8.0 was frozen and never regenerated since, so a one-time conversion is safe and permanent. Real counts (re-measured by grep against the pre-conversion tree, not taken from the ticket estimate): 1265 relref shortcodes (1132 as `{{< relref`, 133 as the no-space `{{<relref` variant) across 191 files, 25 callout shortcodes (18 note, 7 warning, 0 tip/alert) across 20 files -- 18 files carry both. Post-conversion grep confirms 0 remaining shortcode-form relref/callout instances anywhere in the tree. 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), plus a stray whitespace-only `>` artifact line left by the closing tag's indentation -- the same defect pattern already fixed in the 7.4, 7.22, and 7.8 units, recurring a 4th time as predicted. Fixed by re-indenting all blockquote lines to match the list item and dropping the stray line. Checked all 19 other callout-bearing files in this tree: none are indented inside a list, so no further nesting fixes were needed. cli-utilities/redis-cli/_index.md's relrefs were all well-formed here -- unlike 7.22/7.4, this snapshot (like 7.8) has no missing-paren instance. No relref-missing-slash instances found anywhere in this unit either. Verification: full-site hugo builds before/after (non-minified -- the esbuild/cf.reserve minify bug and the develop/clients jupyter-example error are both pre-existing and unrelated), diffed with the DOC-7104-diff-hrefs-fix build/diff_rendered_hrefs.py scoped to operate/rs/8.0/references: 281/281 pages compared, 0 href-set changes. The verification-only patched diff script was staged from origin/DOC-7104-diff-hrefs-fix, then unstaged and reverted before this commit; build/diff_rendered_hrefs.py carries no changes here. Build note: both before and after builds hit the same pre-existing fatal error on content/develop/clients/hiredis/_index.md (jupyter-example shortcode failing on a missing data/examples.json entry, unrelated to this unit's path) after Hugo had already finished rendering and copying all pages, including the full operate/rs/8.0/references tree (281 HTML pages present in both output trees) -- confirmed pre-existing and identical in both builds, so the comparison is unaffected. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

github-actions · 2026-09-23T13:53:05Z

DOC-7104

github-actions · 2026-09-23T13:53:07Z

github-actions · 2026-09-23T13:53:10Z

🧠 Redis Memory

Found 6 related items from repository history:

PR — DOC-7104: Migrate content/operate/rs/7.8/references/ (incl. rest-api) to render hooks

Summary
PR — DOC-7104: Migrate content/operate/rs/7.22/references/ (incl. rest-api) to render hooks

Summary
PR — DOC-7104: Migrate content/operate/rs/7.4/references/ (incl. rest-api) to render hooks

Summary
PR — DOC-7104: Migrate content/operate/rs/references/ (excl. rest-api) to render hooks

Summary
PR — DOC-7104: Migrate content/operate/rs/7.22/ (excl. references) to render hooks

Summary
PR — DOC-7104: Migrate content/operate/rs/installing-upgrading/ to render hooks

Summary

Memory updated at 08f1599

dwdougherty

A few things to fix, but I'll go ahead and approve.

dwdougherty · 2026-09-23T20:50:23Z

 ---

-The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands]({{< relref "/commands" >}}) directly from the command-line terminal or with [interactive mode](#interactive-mode).
+The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands](/commands) directly from the command-line terminal or with [interactive mode](#interactive-mode).


/content/commands/....

dwdougherty · 2026-09-23T20:52:57Z

+[Clustering in Redis Software](/content/operate/rs/8.0/databases/durability-ha/clustering.md) and [Redis Cloud](/content/operate/rc/databases/configuration/clustering.md) differs from the [Redis Open Source cluster](/content/operate/oss_and_stack/management/scaling.md) and works with all standard Redis clients.

-Redis Software blocks most [cluster commands]({{< relref "/commands" >}}?group=cluster). If you try to use a blocked cluster command, it returns an error.
+Redis Software blocks most [cluster commands](/commands?group=cluster). If you try to use a blocked cluster command, it returns an error.


/content/...

dwdougherty · 2026-09-23T20:53:15Z

 ---

-The following tables show which Redis Open Source [connection management commands]({{< relref "/commands" >}}?group=connection) are compatible with standard and Active-Active databases in Redis Software and Redis Cloud.
+The following tables show which Redis Open Source [connection management commands](/commands?group=connection) are compatible with standard and Active-Active databases in Redis Software and Redis Cloud.


/content/...

dwdougherty · 2026-09-23T20:54:21Z

 ---

-The following table shows which Redis Open Source [key (generic) commands]({{< relref "/commands" >}}?group=generic) are compatible with standard and Active-Active databases in Redis Software and Redis Cloud.
+The following table shows which Redis Open Source [key (generic) commands](/commands?group=generic) are compatible with standard and Active-Active databases in Redis Software and Redis Cloud.


/content/....

dwdougherty · 2026-09-23T20:54:38Z

 ---

-The following table shows which Redis Open Source [pub/sub commands]({{< relref "/commands" >}}?group=pubsub) are compatible with standard and Active-Active databases in Redis Software and Redis Cloud.
+The following table shows which Redis Open Source [pub/sub commands](/commands?group=pubsub) are compatible with standard and Active-Active databases in Redis Software and Redis Cloud.


/content/...

dwdougherty · 2026-09-23T20:54:57Z

 ---

-The following table shows which Redis Open Source [scripting and function commands]({{< relref "/commands" >}}?group=scripting) are compatible with standard and Active-Active databases in Redis Software and Redis Cloud.
+The following table shows which Redis Open Source [scripting and function commands](/commands?group=scripting) are compatible with standard and Active-Active databases in Redis Software and Redis Cloud.


/content/...

dwdougherty · 2026-09-23T20:55:23Z

 ---

-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 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 Software and Redis Cloud.


/content/...

dwdougherty · 2026-09-23T20:56:07Z

 ---

-The following table shows which Redis Open Source [transaction commands]({{< relref "/commands" >}}?group=transactions) are compatible with standard and Active-Active databases in Redis 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 Software and Redis Cloud.


/content/...

dwdougherty · 2026-09-23T21:00:52Z

+| [PUT](./backup_reset_status#put-bdbs-actions-backup-reset-status) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status |

 ## Export

 | Method | Path | Description |
 |--------|------|-------------|
-| [PUT]({{< relref "./export_reset_status#put-bdbs-actions-export-reset-status" >}}) | `/v1/bdbs/{uid}/actions/export_reset_status` | Reset database export status |
-| [POST]({{< relref "./export#post-bdbs-actions-export" >}}) | `/v1/bdbs/{uid}/actions/export` | Initiate database export |
+| [PUT](./export_reset_status#put-bdbs-actions-export-reset-status) | `/v1/bdbs/{uid}/actions/export_reset_status` | Reset database export status |
+| [POST](./export#post-bdbs-actions-export) | `/v1/bdbs/{uid}/actions/export` | Initiate database export |

 ## Import

 | Method | Path | Description |
 |--------|------|-------------|
-| [PUT]({{< relref "./import_reset_status#put-bdbs-actions-import-reset-status" >}}) | `/v1/bdbs/{uid}/actions/import_reset_status` | Reset database import status |
-| [POST]({{< relref "./import#post-bdbs-actions-import" >}}) | `/v1/bdbs/{uid}/actions/import` | Initiate manual dataset import |
+| [PUT](./import_reset_status#put-bdbs-actions-import-reset-status) | `/v1/bdbs/{uid}/actions/import_reset_status` | Reset database import status |
+| [POST](./import#post-bdbs-actions-import) | `/v1/bdbs/{uid}/actions/import` | Initiate manual dataset import |

 ## Optimize shards placement

 | Method | Path | Description |
 |--------|------|-------------|
-| [GET]({{< relref "./optimize_shards_placement#get-bdbs-actions-optimize-shards-placement" >}}) | `/v1/bdbs/{uid}/actions/optimize_shards_placement` | Get optimized shards placement for a database  |
+| [GET](./optimize_shards_placement#get-bdbs-actions-optimize-shards-placement) | `/v1/bdbs/{uid}/actions/optimize_shards_placement` | Get optimized shards placement for a database  |


These need work.

dwdougherty · 2026-09-23T21:06:50Z

+| [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 |

 ## Get debug info for the current node

 | Method | Path | Description |
 |--------|------|-------------|
-| [GET]({{< relref "./node#get-debuginfo-node" >}}) | `/v1/debuginfo/node` | Gets debug info for the current node |
-| [GET]({{< relref "./node/bdb#get-debuginfo-node-bdb" >}}) | `/v1/debuginfo/node/bdb/{bdb_uid}` | Gets debug info for a database from the current node |
+| [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 |


…(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 · 2026-09-24T09:41:47Z

Proactively applied the identical fix that #4093's review caught (same pattern: bare /commands?group=x links missing the /content/ prefix, and 7 source-relative refs in rest-api/requests/{bdbs/actions,debuginfo}/_index.md pointing at a directory/file with no extension). This version snapshot is a near-identical copy of 7.22's rest-api tree, so the exact same instances recurred in the same two files. Verified 0 href diffs before/after.

…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>

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

andy-stark-redis · 2026-09-24T10:28:28Z

Also fixed the bare /commands link in references/cli-utilities/redis-cli/_index.md (same shape flagged on #4094).

…r hooks Converts relref link shortcodes and note/tip/warning/alert callout shortcodes to render-hook equivalents across content/operate/rs/8.0/, excluding references/ (done separately in #4098) -- 172 of 190 files, 1,273 relref links and 170 callouts. Found and fixed 33 indented-callout instances and the recurring HGETALL missing-paren relref in databases/connect/troubleshooting-guide.md. Flagged, not fixed: the same 6 pre-existing broken relref targets in new-features-redis-enterprise.md (draft: true, never renders). Included flex/ (4 files) despite it not being named in this unit's original subdirectory list, since the actual scope rule is "every file except references/" and flex/ isn't references/ -- confirmed the resulting file-count math against 8.0's total. Review (round 2) caught three more issues, all fixed -- same as #4095, except this version's port-configurations heading postdates the product rebrand: - Bare /commands links in _index.md and security/access-control/redis-acl-overview.md, missing the /content/ prefix (confirmed identical rendered href either way). - new-features-redis-enterprise.md's 6 dead links: applied the same /content/ prefix for consistency. Cosmetic only. - databases/import-export/flush.md: the port-configurations link's anchor was a stray old absolute URL concatenated into the fragment, predating this migration. Replaced with the real heading slug -- "ports-and-port-ranges-used-by-redis-software" here, not "...-redis-enterprise-software" like 7.22/7.4/7.8, since 8.0's own networking/port-configurations.md heading already uses the current product name. 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>

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>

andy-stark-redis requested a review from kaitlynmichael September 23, 2026 13:53

andy-stark-redis self-assigned this Sep 23, 2026

andy-stark-redis added the infrastructure label Sep 23, 2026

github-actions Bot mentioned this pull request Sep 23, 2026

DOC-7104: Migrate content/operate/rs/7.8/ (excl. references) to render hooks #4099

Merged

6 tasks

andy-stark-redis mentioned this pull request Sep 23, 2026

DOC-7104: Migrate content/operate/rs/8.0/ (excl. references) to render hooks #4100

Merged

3 tasks

andy-stark-redis requested review from dwdougherty and removed request for kaitlynmichael September 23, 2026 15:18

dwdougherty approved these changes Sep 23, 2026

View reviewed changes

github-actions Bot mentioned this pull request Sep 24, 2026

DOC-7104: Migrate content/operate/rs/7.22/references/ (incl. rest-api) to render hooks #4093

Merged

6 tasks

This was referenced Sep 24, 2026

DOC-7104: Migrate content/operate/rs/7.4/references/ (incl. rest-api) to render hooks #4094

Merged

DOC-7104: Migrate content/operate/rs/7.8/references/ (incl. rest-api) to render hooks #4096

Merged

DOC-7104: Fix bare /commands links in redis-cli/_index.md (review)

08f1599

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

github-actions Bot mentioned this pull request Sep 24, 2026

DOC-7104: Migrate content/operate/rs/7.22/ (excl. references) to render hooks #4095

Merged

5 tasks

andy-stark-redis merged commit 6792af1 into main Sep 24, 2026
99 checks passed

andy-stark-redis deleted the DOC-7104-8.0-references branch September 24, 2026 10:49

Conversation

andy-stark-redis commented Sep 23, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Findings

Verification

Test plan

Uh oh!

github-actions Bot commented Sep 23, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 23, 2026

Uh oh!

github-actions Bot commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧠 Redis Memory

Summary

Summary

Summary

Summary

Summary

Summary

Uh oh!

dwdougherty left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andy-stark-redis commented Sep 24, 2026

Uh oh!

andy-stark-redis commented Sep 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

andy-stark-redis commented Sep 23, 2026 •

edited by cursor Bot

Loading

github-actions Bot commented Sep 23, 2026 •

edited by atlassian Bot

Loading

github-actions Bot commented Sep 23, 2026 •

edited

Loading