fix(DOC-1919): fully qualify cloud-stub xrefs to resolve in cloud-docs#438
Merged
Conversation
… prefix The Next steps xrefs to postgres_cdc and mysql_cdc input pages used the unqualified form `xref:components:inputs/...`, which resolves correctly when the page is rendered inside its own component (connect) but fails to resolve when the content is single-sourced into cloud-docs via `include::connect:guides:cloud/aws-iam-aurora.adoc[tag=single-source]`. Antora resolves the `components:` module qualifier against the consuming component's namespace (redpanda-cloud), not the source component's, so the cloud-docs build reports an asciidoctor "missing xref" warning for postgres_cdc.adoc. Add the `connect:` component prefix so the xref resolves cross-component in cloud-docs and continues to resolve locally in rp-connect-docs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
✅ Deploy Preview for redpanda-connect ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
📝 WalkthroughWalkthroughThis pull request updates the "Next steps" section of the AWS IAM Aurora guide document to correct the cross-reference link paths for the Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 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 |
micheleRP
reviewed
Jun 4, 2026
micheleRP
left a comment
micheleRP
left a comment
Contributor
There was a problem hiding this comment.
Final-pass review
Files reviewed: 1 .adoc file (modules/guides/pages/cloud/aws-iam-aurora.adoc, +2/-2)
Assessment: Correct, minimal, well-explained build fix. No blocking issues.
Verification
- ✅ Component name is
connect→connect:prefix is the right qualifier. - ✅ Both xrefs are inside the
tag::single-source[]range (tags at lines 2/285, xrefs at 282–283). - ✅ Target pages exist:
modules/components/pages/inputs/postgres_cdc.adocandmysql_cdc.adoc. - ✅ Root cause confirmed: the consuming component (
cloud-data-platform) has nocomponents/inputs/module, so the unqualified form genuinely breaks on include. - ✅ Single-source wiring confirmed in the cloud-docs stub:
include::connect:guides:cloud/aws-iam-aurora.adoc[tag=single-source]. - ✅ Completeness: these two xrefs are the only cross-component references in the entire single-source range — nothing else shares the bug.
Critical issues
None.
Suggestions
None blocking. The fix matches the single-sourcing convention (cross-component refs in single-sourced content must be component-qualified) and the full-resource-ID guidance.
Minor note (PR description only, no doc change)
The PR body refers to the consuming component as redpanda-cloud; the actual component name is now cloud-data-platform. The fix is correct regardless — just a stale name in the prose.
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
Add the
connect:component prefix to the two Next steps xrefs inaws-iam-aurora.adocso they resolve correctly when the page is single-sourced into cloud-docs.Problem
The Next steps section at the bottom of
modules/guides/pages/cloud/aws-iam-aurora.adocpreviously used the unqualified form:This resolves fine in rp-connect-docs's own build (component
connect) because thecomponents:module is local. But these xrefs are inside thetag::single-source[]range, so cloud-docs (componentredpanda-cloud) includes them via:include::connect:guides:cloud/aws-iam-aurora.adoc[tag=single-source]When Antora processes the included content, it resolves
components:against the consuming component's namespace (redpanda-cloud), not the source component's.redpanda-cloudhas nocomponents/inputs/postgres_cdc.adocpage, so the cloud-docs build emits an asciidoctor "missing xref" warning. This was reported as breaking adjacent PRs' build logs because the temp-overrides in those PRs aggregate both repos.The error first surfaced on cloud-docs main after #612 merged 9a7c3b2c (
DOC-1919: add cloud stub for aws-iam-aurora Connect guide).Fix
Qualify both xrefs with the
connect:component prefix:This resolves correctly in both contexts:
connect:components:inputs/...resolves to the local component (theconnect:prefix is redundant but harmless).connect:components:inputs/...resolves cross-component to the Connect component's pages.Preview pages
Test plan
aws-iam-aurora.adoc → missing postgres_cdc.adoc xrefwarning.🤖 Generated with Claude Code