Skip to content

DOC-7003 retarget dead k8s API anchors to the local reference - #3865

Merged
andy-stark-redis merged 1 commit into
mainfrom
DOC-7003-k8s-api-retargets
Aug 27, 2026
Merged

DOC-7003 retarget dead k8s API anchors to the local reference#3865
andy-stark-redis merged 1 commit into
mainfrom
DOC-7003-k8s-api-retargets

Conversation

@andy-stark-redis

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

Copy link
Copy Markdown
Contributor

Third PR for DOC-7003, covering Part A2 — the Kubernetes API anchor retargets.
Independent of #3863 and #3864, based directly on main, so it can be reviewed and
merged on its own.

The problem

Upstream restructured redis_enterprise_cluster_api.md and
redis_enterprise_database_api.md on master: each file now contains exactly one
heading, so every Go-type anchor we linked (#ldapspec, #ssospec,
#redisenterpriseclusterspec, #redisenterprisedatabasespec) is gone. Four live pages
pointed at them.

Instructive detail from the audit worth keeping in mind for the house rules in a later
PR: our pinned-SHA links to these same upstream files still resolve. Pinning survived;
master rotted.

The judgment calls

The ticket flagged this as not a mechanical retarget, and it isn't — the local pages are
organised by field path (### spec.ldap), not by Go type name, and the string
LdapSpec appears nowhere in them. Each link was resolved on what its sentence promises:

Page Was Now Reasoning
security/authentication/ldap.md:50 #ldapspec …cluster_api#specldap Section opens "Cluster-level LDAP configuration, such as server addresses, protocol, authentication and query settings" — matches the "full details on the available fields" the sentence offers
security/authentication/sso.md:364 #ssospec …cluster_api#specsso Section opens "Cluster-level SSO configuration for authentication to the Cluster Manager UI"
recommendations/node-resources.md:45 #redisenterpriseclusterspec …cluster_api#spec Link text is the bare RedisEnterpriseCluster identifier, so the whole spec table is the faithful target; narrowing to #specredisenterprisenoderesources would make the link say something the sentence doesn't
re-databases/db-controller.md:91 #redisenterprisedatabasespec link deleted The same line already carried a relref to that exact page. Retargeting would have produced the same link twice, so the dead one came out

Per content/operate/kubernetes/AGENTS.md, the RedisEnterpriseCluster link text is left
exactly as it is — custom resource identifiers are never reworded.

These anchors are more stable than the ones they replace

Not by luck. k8s_apis_sync.yaml runs a sed pass over crdoc's output that strips the
RedisEnterpriseCluster. prefix from every heading, which is why the headings read
### spec.ldap. The anchor scheme is ours, not upstream's — these links now rot only
if we change our own sync workflow, rather than whenever upstream renames a Go type.
Recorded as a Constraint: trailer on the commit so a future edit to that sed knows what
depends on it.

Verification

Built the site and checked the rendered ids, not assumed slugs — the ticket specifically
warned not to assume the slug for headings containing dots. The dots are stripped:
### spec.ldap renders as id="specldap".

Check Result
id="spec", id="specldap", id="specsso" on the built cluster API page all present
id="spec" on the built database API page present
Rendered hrefs on all four edited pages resolve to those exact anchors
href="" on the four edited pages zero — no relref silently failed
Topical fit of each target section confirmed by reading the section's lead sentence, not just matching the name

Only the unversioned current pages are touched. The same dead anchors appear across the
7.22/, 7.8.x/ and 8.0/ snapshots; per AGENTS.md a current-version change is never
propagated backward into a frozen snapshot, and the ticket scopes archived trees out.

🤖 Generated with Claude Code


Note

Low Risk
Documentation-only link fixes with no runtime, security, or configuration behavior changes.

Overview
Replaces dead upstream GitHub API anchors (removed when redis-enterprise-k8s-docs restructured headings) with in-site relref links to the synced Kubernetes API reference pages.

On LDAP and SSO auth docs, the RedisEnterpriseCluster API reference now points to #specldap and #specsso on redis_enterprise_cluster_api. Node resources links RedisEnterpriseCluster to #spec instead of #redisenterpriseclusterspec. Database controller drops the redundant GitHub RedisEnterpriseDatabaseSpec link because the same line already links to the local database API page.

Reviewed by Cursor Bugbot for commit 0c6d85e. Bugbot is set up for automated code reviews on this repo. Configure here.

Upstream restructured redis_enterprise_cluster_api.md and
redis_enterprise_database_api.md on master so each file now holds a single
heading, which killed every Go-type anchor we linked. Four live pages pointed at
those anchors; all four now use the local generated API reference instead.

The ticket flagged this as a judgment call rather than a mechanical retarget,
because the local pages are organised by field path and the string LdapSpec
appears nowhere in them. Resolved per link, on what the prose promises rather
than on the old anchor's name. LdapSpec and SsoSpec become the field sections
spec.ldap and spec.sso, whose lead sentences describe cluster-level LDAP and SSO
configuration, so the target matches the "full details on the available fields"
the sentence offers. RedisEnterpriseClusterSpec becomes spec, the whole spec
table, because the link text is the bare custom resource name and narrowing it to
the node-resources field would say something the sentence doesn't. The
RedisEnterpriseDatabaseSpec link was deleted outright rather than retargeted; the
same line already carried a relref to that exact page, so retargeting would have
produced the same link twice.

The reassuring find is that the local anchors are more stable than the ones they
replace, and not by luck. They exist because k8s_apis_sync.yaml runs a sed pass
over crdoc's output that strips the RedisEnterpriseCluster prefix from every
heading, so the scheme is ours to keep rather than upstream's to break. That is a
different stability story from the pinned-SHA links the audit noted surviving, and
a better one.

Learned: the generated k8s API reference's anchors come from our own sed normalisation in the sync workflow, not from upstream headings, so they rot only if we change that workflow.
Constraint: these four links depend on the heading-prefix strip in k8s_apis_sync.yaml; altering that sed renames every anchor on both API reference pages at once.
Directive: don't repoint these at redis-enterprise-k8s-docs on master — the *Spec anchors are gone from it entirely, and only its pinned-SHA URLs still resolve.
Ticket: DOC-7003
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@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 5 related items from repository history (5 new this commit):

Memory updated at 0c6d85e

@andy-stark-redis
andy-stark-redis merged commit a75f8c0 into main Aug 27, 2026
94 checks passed
@andy-stark-redis
andy-stark-redis deleted the DOC-7003-k8s-api-retargets branch August 27, 2026 10:54
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