Skip to content

DOC-7003 fix dead and brittle links in the develop docs - #3864

Merged
andy-stark-redis merged 1 commit into
mainfrom
DOC-7003-develop-link-fixes
Aug 26, 2026
Merged

DOC-7003 fix dead and brittle links in the develop docs#3864
andy-stark-redis merged 1 commit into
mainfrom
DOC-7003-develop-link-fixes

Conversation

@andy-stark-redis

@andy-stark-redis andy-stark-redis commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Second of four PRs for DOC-7003, covering Part A1, A3 and A4 — the develop/ link
fixes. 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

Fix File
A1 — 18 anchored RESP3 links retargeted to relref develop/programmability/lua-api.md
A3 — BLOCK_SIZE link repointed develop/ai/search-and-query/administration/configuration.md
A4 — query string moved before the fragment integrate/railway-redis/_index.md
A4 — MANIFESTO line anchor pinned to a SHA develop/programmability/_index.md
A4 — boringssl line range pinned and corrected operate/rs/security/encryption/tls/ciphers.md
A4 — two scroll-to-text fragments dropped develop/whats-new/7-2.md

21 lines changed across 6 files. Of lua-api.md's 11 distinct anchors, 7 were dead
because the spec never had per-type headings; all 18 links now go through relref, so
the 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:

href="https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol#Bind_(authenticate)"

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.md as a third detector bug alongside the two the audit
already 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:

  • MANIFESTO#L7 was correct all along. Pinned to 3eaa2cdc, so it stays correct.
  • boringsslvar cipherSuites opens at line 99 and the list closes at line 130;
    the link said #L99-L131, one blank line past the end. Pinned to 887d5178 and
    tightened to #L99-L130.

Verification

Built the site and checked every retarget against rendered anchors, not predicted slugs:

  • All 10 distinct anchors lua-api.md now targets are present as real ids on the built
    protocol spec page.
  • #create-a-vector-index present on the built vectors page.
  • Zero href="" on the rendered lua-api.md — no relref silently failed to resolve.
  • The 18 new hrefs reconcile exactly against the per-anchor counts.

Two things to flag

A3 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. #create-a-vector-index is the closest honest target, but the real gap is editorial
and outlives this link fix.

Two more dead relref anchors exist on the protocol spec page, left alone as out of
scope.
eval-intro.md:122 uses #resp-arrays and the generated content/commands/ft.aliaslist.md:78
uses #array; both should be #arrays. Not in Part A, and the second is regenerated
upstream so a local fix would revert. They make good test fixtures for the offline checker
in PR 3.

Also unverified: the railway #tcp-proxying anchor. This PR fixes the URL's structure —
the query string was after the fragment, so ?utm_medium=… was being parsed as part of the
anchor — 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 with relref links to protocol-spec anchors (#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.md repoints the BLOCK_SIZE mention from a dead vectors anchor to #create-a-vector-index. programmability/_index.md pins the Redis MANIFESTO GitHub link to a commit SHA instead of unstable. ciphers.md pins the BoringSSL cipher list link to a SHA and tightens the line range to L99–L130.

railway-redis/_index.md moves UTM query parameters before the #tcp-proxying fragment so tracking params are not treated as part of the anchor. whats-new/7-2.md drops 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.

@github-actions

github-actions Bot commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

DOC-7003

@github-actions

github-actions Bot commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

🧠 Redis Memory

Found 8 related items from repository history (3 new this commit):

Memory updated at cfd0c87

@dwdougherty dwdougherty left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for cleaning these up! Approved.

@andy-stark-redis

Copy link
Copy Markdown
Contributor Author

Thank you for cleaning these up! Approved.

No problem, @dwdougherty - thanks for the review :-)

Base automatically changed from DOC-7003-protocol-spec-streamed-types to main August 26, 2026 13:53
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
andy-stark-redis force-pushed the DOC-7003-develop-link-fixes branch from 668eefb to cfd0c87 Compare August 26, 2026 13:56
@andy-stark-redis
andy-stark-redis merged commit 9feb7b6 into main Aug 26, 2026
92 checks passed
@andy-stark-redis
andy-stark-redis deleted the DOC-7003-develop-link-fixes branch August 26, 2026 14:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants