DOC-2226: Sweep broken dotted-property xref anchors (idseparator migration)#1730
Open
Feediver1 wants to merge 2 commits into
Open
DOC-2226: Sweep broken dotted-property xref anchors (idseparator migration)#1730Feediver1 wants to merge 2 commits into
Feediver1 wants to merge 2 commits into
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
📝 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 docstrings
🧪 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
| "description": "Controls the upload of log segments to Tiered Storage. If set to `false`, this property temporarily pauses all log segment uploads from the Redpanda cluster. When the uploads are paused, the <<cloud_storage_enable_remote_allow_gaps, `cloud_storage_enable_remote_allow_gaps`>> cluster configuration and `redpanda.remote.allowgaps` topic properties control local retention behavior.", | ||
| "related_topics": [ | ||
| "xref:properties/topic-properties.adoc#redpandaremoteallowgaps[`redpanda.remote.allowgaps`]" | ||
| "xref:properties/topic-properties.adoc#redpanda-remote-allowgaps[`redpanda.remote.allowgaps`]" |
Contributor
There was a problem hiding this comment.
Normalize changed xrefs to full Antora resource IDs.
These updated links still use relative or non-prefixed targets (for example xref:./topic-properties.adoc..., xref:../cluster-properties.adoc..., and xref:properties/...). In this overrides file, these should be fully qualified (for example xref:reference:properties/topic-properties.adoc... and xref:reference:properties/cluster-properties.adoc...).
As per coding guidelines, "Always use full Antora resource IDs with module prefixes in xref links within property descriptions" and "Normalize all xref links in property-overrides.json to use full Antora resource IDs after updating".
Also applies to: 1251-1251, 1327-1327, 1351-1351, 1361-1361, 1367-1367, 1370-1370, 2051-2051
🤖 Prompt for 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.
In `@docs-data/property-overrides.json` at 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.
|
|
||
| ifndef::env-cloud[] | ||
| At a cluster-level, compaction is set when xref:reference:cluster-properties.adoc#log_cleanup_policy[`log_cleanup_policy`] or xref:reference:topic-properties.adoc#cleanuppolicy[`cleanup.policy`] are set to either `compact` or `compact,delete`. | ||
| At a cluster-level, compaction is set when xref:reference:cluster-properties.adoc#log_cleanup_policy[`log_cleanup_policy`] or xref:reference:topic-properties.adoc#cleanup-policy[`cleanup.policy`] are set to either `compact` or `compact,delete`. |
Contributor
There was a problem hiding this comment.
Fix topic-properties xref path to the properties reference page.
Use xref:reference:properties/topic-properties.adoc#cleanup-policy[...] here for consistency with canonical property-reference links.
🤖 Prompt for 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.
In `@modules/develop/pages/transactions.adoc` at 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.
| === Configure at topic level | ||
|
|
||
| To override the cluster-level setting at the topic level, set the topic-level property xref:reference:topic-properties.adoc#writecaching[`write.caching`]: | ||
| To override the cluster-level setting at the topic level, set the topic-level property xref:reference:topic-properties.adoc#write-caching[`write.caching`]: |
Contributor
There was a problem hiding this comment.
Update topic-properties links to the canonical properties path.
Both links should target reference:properties/topic-properties.adoc (not reference:topic-properties.adoc) to keep references consistent and avoid invalid targets.
Also applies to: 337-337
🤖 Prompt for 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.
In `@modules/manage/pages/kubernetes/k-manage-topics.adoc` at 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.
| ==== Compacted topics in Tiered Storage | ||
|
|
||
| When you set xref:reference:topic-properties.adoc#cleanuppolicy[`cleanup.policy`] for a topic to `compact`, nothing gets deleted from object storage based on retention settings. When set to `compact,delete`, compacted segments are deleted from object storage based on `retention.ms` and `retention.bytes`. | ||
| When you set xref:reference:topic-properties.adoc#cleanup-policy[`cleanup.policy`] for a topic to `compact`, nothing gets deleted from object storage based on retention settings. When set to `compact,delete`, compacted segments are deleted from object storage based on `retention.ms` and `retention.bytes`. |
Contributor
There was a problem hiding this comment.
Fix the xref target path at Line 1018 (topic-properties page path looks wrong).
The anchor update is good, but xref:reference:topic-properties.adoc#cleanup-policy[...] likely points to a non-canonical location. In this repo, topic property docs are under reference:properties/..., so this xref may fail at build/render time.
Proposed fix
-When you set xref:reference:topic-properties.adoc#cleanup-policy[`cleanup.policy`] for a topic to `compact`, nothing gets deleted from object storage based on retention settings. When set to `compact,delete`, compacted segments are deleted from object storage based on `retention.ms` and `retention.bytes`.
+When you set xref:reference:properties/topic-properties.adoc#cleanup-policy[`cleanup.policy`] for a topic to `compact`, nothing gets deleted from object storage based on retention settings. When set to `compact,delete`, compacted segments are deleted from object storage based on `retention.ms` and `retention.bytes`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| When you set xref:reference:topic-properties.adoc#cleanup-policy[`cleanup.policy`] for a topic to `compact`, nothing gets deleted from object storage based on retention settings. When set to `compact,delete`, compacted segments are deleted from object storage based on `retention.ms` and `retention.bytes`. | |
| When you set xref:reference:properties/topic-properties.adoc#cleanup-policy[`cleanup.policy`] for a topic to `compact`, nothing gets deleted from object storage based on retention settings. When set to `compact,delete`, compacted segments are deleted from object storage based on `retention.ms` and `retention.bytes`. |
🤖 Prompt for 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.
In `@modules/manage/partials/tiered-storage.adoc` at 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.
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>
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
1 participant
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.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