DOC-7003 fix dead and brittle links in the develop docs - #3864
Merged
Conversation
Contributor
Contributor
Contributor
dwdougherty
approved these changes
Aug 26, 2026
dwdougherty
left a comment
Collaborator
There was a problem hiding this comment.
Thank you for cleaning these up! Approved.
Contributor
Author
No problem, @dwdougherty - thanks for the review :-) |
Retargets the 18 anchored RESP3 links in lua-api.md onto the protocol spec page, repoints the BLOCK_SIZE link that named a heading which no longer exists, and repairs four malformed or brittle external links. The lua-api.md links all pointed into redis-specifications on master, where 7 of their 11 distinct anchors were dead because the spec never had per-type headings. All 18 now use relref, so the build validates the page and the earlier PR in this stack supplies the two streamed-type anchors. The prose said "streamed aggregate data types" as well, and that missing "d" is exactly what made the anchor dead, so the link text was corrected to match. Three things did not go as the audit predicted, and two of them changed the edit. The Wikipedia LDAP bind link is not broken. The audit reported that its unescaped closing paren truncates the markdown link, but the rendered HTML carries the full href with the anchor intact and no stray text, because CommonMark permits balanced parentheses inside a link destination and goldmark implements that. The detector regex stopped at the first paren. That line is deliberately untouched. Line numbers could not be verified through WebFetch, which reported the MANIFESTO phrase on line 8 and hedged on the boringssl range. Fetching both files at pinned SHAs and counting lines directly showed the MANIFESTO anchor was right all along, and that the boringssl cipher suite list ends at line 130 rather than the linked 131, so the range now stops where the list does. The BLOCK_SIZE link is a retarget under protest. BLOCK_SIZE is no longer documented anywhere on the vectors page; the only trace is DEFAULT_BLOCK_SIZE inside a TRAINING_THRESHOLD table cell. Pointing at the index creation section is the closest honest target, but the underlying gap is editorial and outlives this link fix. Learned: the audit's paren finding was a third detector bug, not a content defect, so an incoming link finding needs its rendered output checked before it earns an edit. Constraint: the two GitHub line anchors depend on their pinned SHAs; repointing either at a moving branch silently reintroduces line drift. Rejected: escaping the parens in the Wikipedia bind link | it already renders correctly, so the edit would have churned a healthy line on a false positive Directive: don't re-fix the Wikipedia bind link on paren-escaping grounds; check the built HTML first. Gaps: the railway #tcp-proxying anchor is unverified, one weak negative fetch and no corroboration; two dead relref anchors outside this ticket's scope are left in place, in eval-intro.md and the generated ft.aliaslist.md. Ticket: DOC-7003 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
andy-stark-redis
force-pushed
the
DOC-7003-develop-link-fixes
branch
from
August 26, 2026 13:56
668eefb to
cfd0c87
Compare
This was referenced Aug 26, 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
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.
Second of four PRs for DOC-7003, covering Part A1, A3 and A4 — the
develop/linkfixes. Stacked on #3863, which supplies the two streamed-type anchors this PR
links to. Base is set to that branch; review or merge it first.
What changed
relrefdevelop/programmability/lua-api.mdBLOCK_SIZElink repointeddevelop/ai/search-and-query/administration/configuration.mdintegrate/railway-redis/_index.mddevelop/programmability/_index.mdoperate/rs/security/encryption/tls/ciphers.mddevelop/whats-new/7-2.md21 lines changed across 6 files. Of
lua-api.md's 11 distinct anchors, 7 were deadbecause the spec never had per-type headings; all 18 links now go through
relref, sothe build validates the target page. The prose read "streamed aggregate data types",
and that missing "d" is exactly what made the anchor dead, so the link text was
corrected too.
One finding in the ticket is a false positive
The Wikipedia LDAP bind link is not broken, and this PR does not touch it. The audit
reported that its unescaped closing paren truncates the markdown link. The rendered HTML
disagrees:
Full href, anchor intact, no stray text after the link. CommonMark permits balanced
parentheses inside a link destination and goldmark implements that, so the detector's
regex stopping at the first paren is the bug. The target anchor
Bind_(authenticate)also still exists on Wikipedia, so the link is healthy end to end. Worth folding back
into
ANCHOR_AUDIT_FINDINGS.mdas a third detector bug alongside the two the auditalready documents.
Line numbers had to be verified the hard way
WebFetch could not settle either line anchor — it placed the MANIFESTO phrase on line 8
and hedged on the boringssl range with "approximately". Fetching both files at pinned
SHAs and counting lines directly gave the real answers:
#L7was correct all along. Pinned to3eaa2cdc, so it stays correct.var cipherSuitesopens at line 99 and the list closes at line 130;the link said
#L99-L131, one blank line past the end. Pinned to887d5178andtightened to
#L99-L130.Verification
Built the site and checked every retarget against rendered anchors, not predicted slugs:
lua-api.mdnow targets are present as real ids on the builtprotocol spec page.
#create-a-vector-indexpresent on the built vectors page.href=""on the renderedlua-api.md— no relref silently failed to resolve.Two things to flag
A3 is a retarget under protest.
BLOCK_SIZEis no longer documented anywhere on thevectors page — the only trace is
DEFAULT_BLOCK_SIZEinside aTRAINING_THRESHOLDtablecell.
#create-a-vector-indexis the closest honest target, but the real gap is editorialand outlives this link fix.
Two more dead relref anchors exist on the protocol spec page, left alone as out of
scope.
eval-intro.md:122uses#resp-arraysand the generatedcontent/commands/ft.aliaslist.md:78uses
#array; both should be#arrays. Not in Part A, and the second is regeneratedupstream so a local fix would revert. They make good test fixtures for the offline checker
in PR 3.
Also unverified: the railway
#tcp-proxyinganchor. This PR fixes the URL's structure —the query string was after the fragment, so
?utm_medium=…was being parsed as part of theanchor — which is correct regardless. Whether that anchor exists rests on one weak negative
fetch, so I have not claimed it either way.
🤖 Generated with Claude Code
Note
Low Risk
Documentation-only link and anchor updates with no changes to application code, configuration defaults, or security-sensitive runtime behavior.
Overview
This PR repairs broken or fragile documentation links across six files as part of DOC-7003 (develop link fixes), with no product or API behavior changes.
The largest edit is in
lua-api.md: 18 external RESP3 GitHub spec URLs are replaced withrelreflinks toprotocol-specanchors (#maps,#sets,#nulls,#booleans, and related types). Unsupported Lua API types are linked to#attributes,#streamed-strings, and#streamed-aggregated-data-types, and the prose is corrected from “streamed aggregate” to “streamed aggregated” to match the real heading.configuration.mdrepoints theBLOCK_SIZEmention from a dead vectors anchor to#create-a-vector-index.programmability/_index.mdpins the Redis MANIFESTO GitHub link to a commit SHA instead ofunstable.ciphers.mdpins the BoringSSL cipher list link to a SHA and tightens the line range to L99–L130.railway-redis/_index.mdmoves UTM query parameters before the#tcp-proxyingfragment so tracking params are not treated as part of the anchor.whats-new/7-2.mddrops brittle scroll-to-text fragments from two redis.io blog URLs.Reviewed by Cursor Bugbot for commit cfd0c87. Bugbot is set up for automated code reviews on this repo. Configure here.