DOC-6909 Migrate develop/clients/redis-py to portable Markdown links and callouts - #3798
DOC-6909 Migrate develop/clients/redis-py to portable Markdown links and callouts#3798andy-stark-redis wants to merge 1 commit into
Conversation
🧠 Redis MemoryFound 10 related items from repository history:
Memory updated at f642cb9 |
4d327ed to
73843d7
Compare
73843d7 to
d4786e2
Compare
d4786e2 to
ec9ca85
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit ec9ca85. Configure here.
ec9ca85 to
ead7ad9
Compare
…and callouts Converts one section end to end as the investigation's proof: 147 links to repo-root-relative /content/ paths, and 8 note shortcodes to native blockquote alerts. The source is now standard Markdown that resolves in VS Code and GitHub as well as here, and the published output is unchanged. Repo-root-relative was chosen over source-relative after review feedback about long parent-traversal chains. Both GitHub's rendered view and VS Code resolve a leading slash against the repository root, so the /content/ prefix is what makes a link work in all three places at once. The notation also matters on the doubly-mounted Active-Active tree, where the same source is served under two URLs. There, repo-root-relative resolves exactly as relref does, while source-relative diverges by keeping the reader inside the second mount. This form is the faithful relref replacement. Verified against the relref baseline: no href differences across the migrated pages or either mount, no new warnings, no errors. Note that HTML parity is not feed parity, which is why the pipeline change lower in this stack is a prerequisite rather than a follow-up. Ticket: DOC-6909 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ead7ad9 to
f642cb9
Compare
dwdougherty
left a comment
dwdougherty
left a comment
There was a problem hiding this comment.
I tested a bunch of links and looked at some of the callouts. LGTM.
|
Thanks @dwdougherty ! |
2 participants
Part 4 of 4. Stack: #3795 → #3796 → #3797 → #3798 (this)
What this is
One section migrated end to end, as the investigation's proof: 147 links to repo-root-relative
/content/paths and 8 note shortcodes to native blockquote alerts. The source becomes standard Markdown that resolves in VS Code and GitHub as well as in Hugo, with unchanged published output.Why
/content/rather than../../../@dwdougherty objected on #3732 that source-relative links produced long parent-traversal chains — fair: 3 levels on 34 of the 147 links, 2 or more on 100. Both GitHub's rendered view and VS Code resolve a leading slash against the repository root, so the
/content/prefix is what makes one link work in all three places.It also behaves better on the doubly-mounted Active-Active tree, where the same source is served under two URLs:
/operate/rs/operate/rcrelref/operate/rs/…/operate/**rs**/…/content/…md/operate/rs/…/operate/**rs**/…../…md/operate/rs/…/operate/**rc**/…Repo-root-relative tracks
relrefexactly; source-relative is the one that diverges. So this notation is the faithfulrelrefreplacement, and the form it replaces was quietly changing behaviour on that tree.Verified
No href differences across the migrated pages or either Active-Active mount, no new warnings, no errors, build time unchanged.
Caveat worth stating plainly: HTML parity is not feed parity. The
.md/.jsonoutputs were broken for these pages both before and after the notation change, which is why the pipeline fix in #3796 is a prerequisite in this stack rather than a follow-up.Open question for reviewers
relrefis unaffected and still works — 30,218 calls across 4,027 files build warning-free alongside these plain links. But Hugo resolves/develop/x,/develop/x.mdand baredevelop/xto the same correct URL with no warning, so it cannot distinguish "portable" from "merely working". A non-/content/link builds a clean site and is silently broken in GitHub and VS Code. If we standardise on this, it wants a lint —.claude/hooks/check_shortcode_paths.pyvalidatesrelref/image/embed-*today and gives plain Markdown links no validation at all.Note
Low Risk
Documentation-only link and callout formatting in the redis-py section; no application or runtime code changes.
Overview
This PR migrates the entire
content/develop/clients/redis-pysection to portable Markdown so links work in Hugo, GitHub, and VS Code without changing published URLs.Internal links: Hugo
{{< relref "..." >}}calls are replaced with repo-root-relative paths such as/content/develop/clients/redis-py/connect.md#...(and_index.mdwhere needed). That covers cross-links to other develop/operate/integrate/command pages across the redis-py guides (connect, async, failover, search examples, etc.).Callouts: Eight
{{< note >}}shortcodes become GitHub-flavored alert blockquotes (> [!NOTE]with blockquoted body), including notes on TLS/AMR, client-side caching, SCH/RESP3, query dialect defaults, and Pub/Sub failover message loss.Hugo shortcodes for examples (
clients-example,jupyter-example,alert, etc.) are unchanged; this is a notation-only docs refactor for link portability and editor preview.Reviewed by Cursor Bugbot for commit f642cb9. Bugbot is set up for automated code reviews on this repo. Configure here.