DOC-7003 retarget the remaining dead k8s API anchors - #3879
Merged
Conversation
Clears the 26 remaining Go-type anchors pointing into the generated Kubernetes API reference, across vault.md and the three upgrade pages. Same root cause as the four fixed in a75f8c0: the local pages are organised by field path, so a Go type name was never an anchor on them. The checker from the B1 branch found these, and nothing before it could. The external-anchor audit could not see them by construction, because they are relrefs rather than external URLs, and the build cannot see them because relref validates the page and never the heading. Counting distinct anchors understated this badly. There are 10 distinct (file, anchor) pairs but 26 instances, and they are not duplicates of each other: eight separate links share the dead anchor #redisenterprisespec while each names a different field in its link text, so each one needed its own target. The right unit of work here was the link, not the anchor. Targets were derived rather than guessed, by locating each field name in the API reference's own tables and taking the containing section. That produced eight distinct precise targets where a blanket #spec would have been defensible but worse -- the six certificate fields belong to spec.certificates, the five backup credentials to their own spec.backup.* subsections, the two replica-source secrets to spec.replicaSources. Only the fields that genuinely live in the top-level table became #spec. The strongest hint that this was the right approach is that vault.md already used correct field-path anchors for four of its links, alongside the broken Go-type ones. The convention was known and applied inconsistently, so matching the working links was the local standard rather than an invention. Two limits of my own extraction are worth recording. It first reported globalConfigurations as a field that did not exist on its page, because the table cell wraps it in an anchor tag and the regex only matched bare cell text -- the field is there, with a section of its own. And three links whose text reads "REDB spec.redisVersion field" rather than a bare field name went unmatched until the instance counts were reconciled, 23 against the checker's 26. Both were caught by insisting the two numbers agree before editing anything. Learned: counting distinct dead anchors is the wrong unit when one anchor serves many links -- eight links shared #redisenterprisespec and each needed a different target, so reconcile instances against distinct pairs before estimating the work. Constraint: these targets are field-path slugs produced by the sed pass in k8s_apis_sync.yaml, so they move together if that workflow changes. Directive: derive an API-reference anchor by finding the field in the reference's own tables; don't blanket-retarget to #spec, and match the field-path anchors already working in the same file. Gaps: 86 findings remain repo-wide outside the Kubernetes pages, unverified individually; the two /spec targets for redisVersion and redisUpgradePolicy send a reader to a large table because neither field has a section of its own. Ticket: DOC-7003 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
Contributor
Contributor
🧠 Redis MemoryFound 5 related items from repository history (5 new this commit):
Memory updated at e463891 |
This was referenced Aug 27, 2026
kaitlynmichael
approved these changes
Aug 27, 2026
Contributor
Author
|
Thanks @kaitlynmichael ! |
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.
Follow-up to
a75f8c03b(Part A2), clearing the 26 remaining dead Go-type anchorsinto the generated Kubernetes API reference. Based on
main. Same root cause: thosepages are organised by field path, so a Go type name was never an anchor on them.
Found by the Part B1 checker (#3867), and
nothing before it could see them — the external audit couldn't by construction (these are
relrefs, not external URLs), and the build can't becauserelrefvalidates the page andnever the heading.
Counting distinct anchors understated this
There are 10 distinct
(file, anchor)pairs but 26 instances, and they are notduplicates. Eight separate links share
#redisenterprisespecwhile each names adifferent field in its link text, so each needed its own target. The unit of work was
the link, not the anchor.
Targets were derived, not guessed
Each field name was located in the API reference's own tables and the containing section
taken. That gives eight precise targets where a blanket
#specwould have been defensiblebut worse:
apiCertificateSecretName,cmCertificateSecretName,metricsExporterCertificateSecretName,proxyCertificateSecretName,syncerCertificateSecretName,ldapClientCertificateSecretName#speccertificatesawsSecretName,sftpSecretName,swiftSecretName,absSecretName,gcsSecretName#specbackups3/sftp/swift/abs/gcsclientKeySecret,serverCertSecret#specreplicasourcesglobalConfigurations#specglobalconfigurationslicenseSecretName,clusterCredentialSecretName,secretName,redisVersion,redisUpgradePolicy#spec(these genuinely live in the top-level table)The strongest evidence this was right:
vault.mdalready used correct field-path anchorsfor four of its links (
#speccertificates,#specldap,#specssosaml,#specuserdefinedmodulessourcehttps) alongside the broken Go-type ones. The convention wasknown and applied inconsistently, so matching the working links is the local standard
rather than my invention.
Verification
#redisenterprisespecis genuinely absentrelrefstill resolvesThe
+26on the OK count is the check that matters: findings could drop to zero becauselinks vanished. The OK count rising by exactly 26 proves they now resolve.
Rendered
vault.mdshows 10 hrefs to#speccertificates— 6 retargeted plus the 4 alreadycorrect, which reconciles.
Two limits of my own tooling, recorded
globalConfigurationsas not existing on its page.It does, with a section of its own; the table cell wraps it in an anchor tag and my regex
only matched bare cell text.
[REDBspec.redisVersionfield]rather than a bare field name wentunmatched, giving 23 against the checker's 26.
Both were caught by refusing to edit until the two instance counts agreed — which is the
only reason this PR isn't three links short.
Still open
86 checker findings remain repo-wide outside Kubernetes. Not touched here; they span several
product areas and mix mechanical retargets with genuine editorial decisions (one target page
split "Create certificates" into four narrower sections).
🤖 Generated with Claude Code
Note
Low Risk
Documentation-only anchor updates with no runtime, security, or configuration impact.
Overview
DOC-7003 follow-up: retargets 26 internal
relreflinks that still pointed at obsolete Go-type fragments (for example#redisenterprisespec,#redisenterprisedbspec) on generated Kubernetes API reference pages, which only expose field-path section anchors.In
vault.md, API field links in the Vault secrets table now jump to the matching sections—#spec,#speccertificates,#specreplicasources, per-backup-provider anchors,#specglobalconfigurations, and similar—instead of a single broken spec-type anchor.The upgrade pages (
upgrade-redis-cluster.md,openshift-cli.md,upgrade-olm.md) get the same treatment forspec.redisVersion,redisUpgradePolicy, and related REC/REDB API links (#specrather than#redisversion/#redisupgradepolicy).No product or operator behavior changes; this is link hygiene so readers land on the right API table rows.
Reviewed by Cursor Bugbot for commit e463891. Bugbot is set up for automated code reviews on this repo. Configure here.