DOC-2226: Sweep broken dotted-property xref anchors (idseparator migration)#1730
Merged
Conversation
The migration from no-separator to hyphen-separator anchor IDs (idseparator: '-') is half-finished. Existing xrefs in the no-separator form (e.g., #retentionms) still load the page but silently fail to jump to the target section because Antora does not validate URL fragments. This PR sweeps the hand-edited referrers that point at the topic-properties page. Per the ticket, generated content under modules/reference/partials/properties/ and modules/reference/attachments/ is intentionally not touched here — those land on the next property-docs regen (the override source in docs-data/property-overrides.json is updated so the regen produces correct anchors). 49 anchor substitutions across 8 files: - modules/develop/pages/transactions.adoc (1) - modules/get-started/pages/release-notes/redpanda.adoc (1) - modules/manage/pages/cluster-maintenance/compaction-settings.adoc (5) - modules/manage/pages/cluster-maintenance/topic-property-configuration.adoc (8) - modules/manage/pages/kubernetes/k-manage-topics.adoc (3) - modules/manage/pages/schema-reg/schema-id-validation.adoc (12) - modules/manage/partials/tiered-storage.adoc (1) - docs-data/property-overrides.json (18) Also fixes one off-target xref in the override JSON: a default_topic_replication reference pointed at topic-properties.adoc but default_topic_replication is a cluster property. Removed the duplicate topic-properties reference; the override already had the correct cluster-properties.adoc xref alongside. Two anchor renames carried in this sweep (where the property was renamed, not just the anchor separator): - redpanda.value.schema.validation -> redpanda.value.schema.id.validation (anchor: redpandavalueschemavalidation -> redpanda-value-schema-id-validation) - redpanda.key.schema.validation -> redpanda.key.schema.id.validation (anchor: redpandakeyschemavalidation -> redpanda-key-schema-id-validation) Not addressed in this PR (flagged for follow-up): - xref:reference:properties/topic-properties.adoc#redpanda-iceberg-enabled appears in 3 places (property-overrides.json, cluster-properties.adoc, attachments JSON) but no `=== redpanda.iceberg.enabled` H3 exists on topic-properties. The property may have been renamed (redpanda.iceberg.mode subsumes the enabled toggle) or deprecated. Needs human review of intent before fixing. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR corrects documentation cross-reference anchors across configuration property references. The changes standardize anchor names from concatenated forms (e.g., Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs-data/property-overrides.json`:
- Line 309: The xref entries in property-overrides.json use non-prefixed targets
(e.g.
"xref:properties/topic-properties.adoc#redpanda-remote-allowgaps[`redpanda.remote.allowgaps`]")
and must be normalized to full Antora resource IDs; update each affected xref
(including the occurrences referenced around lines with
"xref:properties/topic-properties.adoc", "xref:cluster-properties.adoc", and
other "xref:properties/..." matches noted in the comment) to use the
module-prefixed form like
"xref:reference:properties/topic-properties.adoc#...[`...`]" (or the appropriate
module prefix for cluster properties) so all links in property-overrides.json
are full Antora resource IDs. Ensure you replace every listed occurrence (1251,
1327, 1351, 1361, 1367, 1370, 2051 and the shown line) consistently.
In `@modules/develop/pages/transactions.adoc`:
- Line 326: The topic-properties xref is using the wrong path; update the link
in the sentence that currently uses
xref:reference:topic-properties.adoc#cleanup-policy[...] to the canonical
properties reference path
xref:reference:properties/topic-properties.adoc#cleanup-policy[...] so the
cleanup.policy anchor points to properties/topic-properties.adoc instead of
topic-properties.adoc.
In `@modules/manage/pages/kubernetes/k-manage-topics.adoc`:
- Line 329: The Asciidoc link target for the topic property currently points to
reference:topic-properties.adoc; update both occurrences (the link around
`write.caching` in k-manage-topics.adoc and the other instance noted at the same
section) to use the canonical path reference:properties/topic-properties.adoc so
the links correctly resolve to the properties/topic-properties.adoc reference
file.
In `@modules/manage/partials/tiered-storage.adoc`:
- Line 1018: The xref target is pointing to reference:topic-properties.adoc
which is non-canonical; update the xref in the sentence that currently reads
xref:reference:topic-properties.adoc#cleanup-policy[...] to the repository's
canonical location under reference:properties (e.g.,
xref:reference:properties/topic-properties.adoc#cleanup-policy[...] ) so the
link resolves correctly to the topic properties cleanup.policy anchor.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: ffcf029a-3e82-4a78-956f-f950d8f2c562
📒 Files selected for processing (8)
docs-data/property-overrides.jsonmodules/develop/pages/transactions.adocmodules/get-started/pages/release-notes/redpanda.adocmodules/manage/pages/cluster-maintenance/compaction-settings.adocmodules/manage/pages/cluster-maintenance/topic-property-configuration.adocmodules/manage/pages/kubernetes/k-manage-topics.adocmodules/manage/pages/schema-reg/schema-id-validation.adocmodules/manage/partials/tiered-storage.adoc
Companion to the previous commit's source-override fix. Apply the broken-anchor → hyphenated-anchor mapping to the four generated files under modules/reference/partials/properties/ and modules/reference/attachments/, so this PR ships a complete sweep rather than leaving the generated files for a later regen cycle. Approach: ran `doc-tools generate property-docs --tag v26.1.9 --generate-partials` to produce the full regen, then reverted the four generated files to pre-regen state and applied ONLY the anchor substitution (same mapping the previous commit used on the hand-edited referrers). End state is mechanically equivalent to a regen with the unrelated source drift reverted, but achieved without committing the drift in the first place. Drift the regen would have introduced (intentionally NOT applied here; needs a separate coordinated property-docs resync ticket): - delete_topic_enable: description rewrite + new Related topics section - raft_election_timeout_ms: type change string → integer, default null → 1500 - features_auto_finalization: "Introduced in v26.1.9" annotation - iceberg_rest_catalog_gcp_user_project: NOTE added, redpanda-cloud tags repositioned, default text adjusted 36 anchor substitutions in this commit: - modules/reference/partials/properties/cluster-properties.adoc (17) - modules/reference/attachments/redpanda-properties-v26.1.9.json (18) - modules/reference/partials/properties/object-storage-properties.adoc (1) Plus one default_topic_replication dedup: - modules/reference/partials/properties/broker-properties.adoc (dropped the off-target topic-properties xref; only the correct cluster-properties xref remains) - modules/reference/attachments/redpanda-properties-v26.1.9.json (same dedup in the schema_registry_replication_factor related_topics list) After this commit, the only remaining "broken" topic-properties anchor in the entire repo is `#redpanda-iceberg-enabled` (3 refs, all in generated files), which is flagged for follow-up in the previous commit message — no matching H3 on topic-properties; the property may have been renamed or deprecated. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
micheleRP
reviewed
Jun 5, 2026
Contributor
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Review: DOC-2226 anchor sweep
Verified the anchor migration end-to-end — this is clean, correct, and complete. No blocking issues.
Correctness
- All 26 distinct new anchors map to real
===headings inmodules/reference/partials/properties/topic-properties.adoc(checked each one, e.g.cleanup.policy→#cleanup-policy,max.compaction.lag.ms→#max-compaction-lag-ms). - Also caught and fixed two literal-dotted old forms (
#max.compaction.lag.ms,#min.compaction.lag.ms), not just the no-separator forms. - Both property renames are handled correctly:
redpanda.{key,value}.schema.validation→…schema.id.validation. default_topic_replicationdedup is right — it's a cluster property, so the off-targettopic-properties.adocxref is correctly removed and the single remaining related-topic inbroker-properties.adocis inlined (matches generator output for one item).- The
k-manage-topics.adoclines use the short pathreference:topic-properties.adoc(noproperties/), which resolves via:page-aliases: reference:topic-properties.adocon the canonical page — so those anchor fixes are valid.
Completeness
- No broken
topic-properties.adoc#anchors remain in any file outside this PR's changed set (full working-tree grep). - cloud-docs, rp-connect-docs, and redpanda-labs have 0 topic-properties anchor references — docs is the only affected repo, so "possibly cloud-docs" from the ticket needs no further action.
- Other property pages (cluster/broker/object-storage) are snake_case and never had the dot→hyphen issue;
topic-propertiesis the only dotted-name page.
Generated-file edits
Editing the generated partials + attachment JSON directly deviates from the usual "edit overrides, regenerate" rule, but it's the right call here and well documented: docs-data/property-overrides.json was updated in tandem (so a future regen won't regress), and the unrelated source drift was reverted to keep this an anchor-only sweep.
Follow-ups (correctly deferred, not blockers)
#redpanda-iceberg-enabled(3 refs in generated files) — a different bug class: a stale reference to a renamed/deprecated property with no matching=== redpanda.iceberg.enabledheading (likely subsumed byredpanda.iceberg.mode). Worth a dedicated ticket to triage intent rather than guessing the target.- property-docs resync — the unrelated source drift (
raft_election_timeout_mstype change,delete_topic_enablerewrite,features_auto_finalizationannotation,iceberg_rest_catalog_gcp_user_projectNOTE) is intentionally out of scope here; coordinate it in a separate ticket as the DOC-2226 description recommends.
Both follow-ups are already captured in the PR's checklist. LGTM.
micheleRP
approved these changes
Jun 5, 2026
Addresses PR review feedback on the anchor sweep. Two passes:
1. Path normalization: convert every non-canonical xref targeting
topic-properties.adoc or cluster-properties.adoc to the full Antora
resource ID `xref:reference:properties/{topic,cluster}-properties.adoc`.
Covers `xref:./`, `xref:../`, `xref:properties/`, `xref:cluster-properties.adoc`,
and `xref:reference:cluster-properties.adoc` variants across
property-overrides.json, transactions.adoc, k-manage-topics.adoc,
tiered-storage.adoc, and the matching generated partials and
attachment JSON.
2. Broken anchor cleanup: 8 renames where target moved/renamed
(cloud_storage_enabled and cloud_storage_enable_remote_* now in
object-storage-properties; initial_retention_local_target_* and
retention_local_target_* gained `_default` suffix). 4 entries dropped
where the target property is no longer documented (compaction_strategy,
flush_bytes, flush_ms, redpanda-iceberg-enabled).
Validated: all 317 canonical xrefs across the 7 modified files now
resolve to existing anchors; 0 broken refs remain.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
Fix the half-finished migration of dotted-property xref anchors. With
idseparator: '-'(the Antora 3.x default), the propertyretention.msnow renders as#retention-ms. Existing xrefs that use the old no-separator form (#retentionms) still load the page but silently fail to jump to the target section because Antora doesn't validate URL fragments.PR #1728 (DOC-2222) fixed the
retention.*anddelete.retention.*subset earlier; this PR covers the rest of the sweep.Resolves https://redpandadata.atlassian.net/browse/DOC-2226
What's in this PR (two commits)
Commit 1: source-side fixes — 49 substitutions across 8 hand-editable files (override JSON + referrer pages).
Commit 2: generated-partial fixes — 36 anchor substitutions plus one
default_topic_replicationdedup applied directly to the four generated files (cluster-properties.adoc,broker-properties.adoc,object-storage-properties.adoc, andredpanda-properties-v26.1.9.json).Approach for commit 2: ran
doc-tools generate property-docs --tag v26.1.9 --generate-partialsto produce the full regen, then reverted the four generated files to pre-regen state and applied ONLY the anchor substitution (same mapping the previous commit used). End state is mechanically equivalent to a regen with the unrelated source drift reverted.Files touched
Hand-edited
docs-data/property-overrides.jsonmodules/manage/pages/schema-reg/schema-id-validation.adocmodules/manage/pages/cluster-maintenance/topic-property-configuration.adocmodules/manage/pages/cluster-maintenance/compaction-settings.adocmodules/manage/pages/kubernetes/k-manage-topics.adocmodules/develop/pages/transactions.adocmodules/get-started/pages/release-notes/redpanda.adocmodules/manage/partials/tiered-storage.adocGenerated (anchor-only delta vs pre-regen state)
modules/reference/partials/properties/cluster-properties.adocmodules/reference/attachments/redpanda-properties-v26.1.9.jsonmodules/reference/partials/properties/object-storage-properties.adocmodules/reference/partials/properties/broker-properties.adocTwo property-rename fixes (carried inside this anchor sweep)
The old anchor forms below referred to a property name that has since been renamed. The fix updates them to the current property's anchor:
redpandavalueschemavalidation→redpanda-value-schema-id-validation(property:redpanda.value.schema.validation→redpanda.value.schema.id.validation)redpandakeyschemavalidation→redpanda-key-schema-id-validation(property:redpanda.key.schema.validation→redpanda.key.schema.id.validation)One off-target xref deduped
The schema-registry
schema_registry_replication_factorrelated_topics had adefault_topic_replicationxref pointing attopic-properties.adoc, butdefault_topic_replicationis a cluster property. Removed the off-target topic-properties xref in three places (the override JSON, the generated broker-properties partial, and the attachment JSON).Drift NOT applied (intentional)
The full property-docs regen would have introduced these source-side changes alongside the anchor fixes. They are reverted in commit 2 so this PR ships a clean anchor sweep only:
delete_topic_enable: description rewrite + new Related topics sectionraft_election_timeout_ms: type changestring→integer, defaultnull→1500features_auto_finalization:Introduced in v26.1.9annotationiceberg_rest_catalog_gcp_user_project: NOTE added, redpanda-cloud tags repositioned, default text adjustedRecommend a separate ticket for the coordinated property-docs resync to land these intentionally.
Flagged for follow-up (not in this PR)
xref:reference:properties/topic-properties.adoc#redpanda-iceberg-enabledappears in 3 places (property-overrides.json,cluster-properties.adoc, attachments JSON), but no=== redpanda.iceberg.enabledH3 exists on the topic-properties page. The property may have been renamed (redpanda.iceberg.modelikely subsumes the enabled toggle) or deprecated. Needs human review of intent before fixing the target.Test plan
ERROR (asciidoctor)lines related to topic-properties anchors.redpanda.value.schema.id.validationreference on the schema-id-validation page) and confirm the page jumps to the correct anchor ontopic-properties/.docs-data/property-overrides.jsonstill parses as valid JSON.modules/reference/attachments/redpanda-properties-v26.1.9.jsonstill parses as valid JSON.redpanda-iceberg-enabledreferences and decide whether to update the target anchor or remove the references entirely.Page previews
🤖 Generated with Claude Code