Update component xrefs for unified navigation#285
Conversation
Add a new lab demonstrating Redpanda's shadow linking feature for disaster recovery on Kubernetes. The lab deploys two single-node clusters and configures continuous replication of topics, consumer group offsets, and Schema Registry data. Includes three demo scenarios: - Basic topic shadowing - Schema Registry shadowing - Consumer group failover Based on https://github.com/pmw-rp/shadowing-demo
Replace bash wrapper scripts with direct rpk commands in the README. Users can now copy commands directly from the documentation instead of running numbered scripts. This makes the lab clearer and more educational.
- Use correct xref path for shadow linking docs - Add ^ to external links for new tab behavior - Fix invalid category: Replication -> Data Replication
- Add kind and Docker to prerequisites - Add step to create kind cluster before running setup - Update clean up to delete kind cluster - Add .gitignore for pid files
- Add progress messages for each step - Suppress helm notes, repo updates, and K8s warnings - Add set -e to exit on errors - Show next steps on completion
Use helm upgrade --install so script can be re-run
- Updated xrefs: ROOT → streaming - Updated xrefs: redpanda-connect → connect - Updated xrefs: redpanda-labs → labs - Fixed page-context-links
- Changed all :ROOT: to :streaming: in xrefs and includes - Fixed connect:streaming:about to connect:get-started:about - Page aliases with version numbers left unchanged
|
Jira: DOC-2180 |
❌ Deploy Preview for redpanda-labs-preview failed. Why did it fail? →
|
There was a problem hiding this comment.
Review
Major rework needed before this PR ships alongside the other 13 in the rollout. The component rename + xref sweep itself is clean, but the PR pulls in an unfinished lab (kubernetes/stretch-cluster) and uses the wrong attribute key (page-header-data vs the rest of the rollout's component-metadata).
Critical
-
docs/local-antora-playbook.ymlstill references the old component name in three places:- line 3:
start_page: redpanda-labs:ROOT:index.adoc - line 55:
component: redpanda-labs(generate-index-dataextension) - line 72:
'redpanda-labs'(replace-attributes-in-attachmentsextension)
Local dev builds and the docker_labs index data will both break. Fix: swap all three to
labs. - line 3:
-
kubernetes/stretch-cluster/is not a finished lab. The README itself states:This is an educational lab demonstrating Stretch Cluster concepts and infrastructure setup… Full Stretch Cluster deployment requires additional operator configuration for multicluster coordination (TLS certificates for inter-operator communication). This lab focuses on infrastructure setup and architecture understanding.
It also notes the StretchCluster shows "Waiting for controller" and NodePools show "NotBound" — i.e., it does not actually deploy a working stretch cluster. Should not ship under "Disaster Recovery / High Availability" lab categories. Fix: split into a separate PR once it actually works, or label clearly as a scaffolding/demo and move out of the unified-nav PR.
-
kubernetes/stretch-cluster/README.adocuses emojis throughout:⏱️(line 26),✅(lines 355–363),❌(lines 369–375). Style guide forbids emojis in docs. -
No
docs/modules/kubernetes/pages/stretch-cluster.adocexists, so the stretch-cluster lab ships only as a repo README (not on the docs site). If intentional, fine — but inconsistent with shadow-linking, which has both. -
Heading case in
kubernetes/stretch-cluster/README.adocH2s: "Example Configurations", "Understanding the Architecture", "What You Learned", "Next Steps for Production Deployment". Project rule is sentence case for H2+.
Suggestions
-
Attribute key mismatch (coordination).
docs/antora.ymladdspage-header-data, but the rest of the rollout (rp-connect-docsredpanda-data/rp-connect-docs#427,cloud-docsredpanda-data/cloud-docs#578,docsredpanda-data/docs#1698-redpanda-data/docs#1705) usescomponent-metadata. Thedocs-uiv3 helpers (sort-components.js,get-header-data.js,get-header-color.js) readcomponent-metadata. If this PR ships as-is, labs likely falls out of the sidebar or renders with stale metadata. Fix: rename tocomponent-metadata. -
The new
shadow-linking/README.adocanddocs/modules/kubernetes/pages/shadow-linking.adocare byte-identical (218 lines each). Consider single-sourcing one from the other (e.g.include::from the canonical) to avoid drift. -
ai-agents/langchain-agent/README.adocis well-structured (learning objectives, prerequisites, clear steps) — good template for the other new labs to follow.
New labs assessment
shadow-linking: 218-line README + 56-line setup.sh + 4 resource YAMLs. Polished, clear prereqs, structured steps, has a docs-site page. Ready to ship.stretch-cluster: 692-line README + 696-line setup.sh + verify.sh + cleanup.sh + 7 resource YAMLs. README openly admits the lab does not produce a working cluster and is "demonstrating concepts." Has emojis, Title Case H2s, no docs-site page. Not ready — pull out of this PR.
Coordination risk
- Attribute key (
page-header-data) doesn't match the rest of the rollout — must be reconciled before merge, otherwise labs won't render in the unified sidebar. - Component rename consistent in user-visible page content for the files touched (
redpanda-labs:→labs:,redpanda-connect:→connect:,ROOT:→streaming:,redpanda-cloud:→cloud-data-platform:). docs-siteredpanda-data/docs-site#173 production playbook currently pointsredpanda-labsatbranches: mainbutmainstill hasname: redpanda-labs— production build won't find alabscomponent. Either this PR must merge first, or docs-site must point at the feature branch.- Legacy
:page-aliases: 23.3@ROOT:…entries (10 instances inclients/chat-room/*/README.adocanddocs/modules/ROOT/pages/index.adoc) are preserved as-is. Versioned aliases pointing back at the old name are intentionally backwards-compatible — fine to leave.
See docs-site redpanda-data/docs-site#173 for cross-rollout notes (suggested approval order + verification steps).
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Approved on the assumption that the 5 Critical items in the review comment above are addressed before merge: (1) fix the 3 stale redpanda-labs references in docs/local-antora-playbook.yml (lines 3, 55, 72) → labs, (2) pull kubernetes/stretch-cluster/ out of this PR — its own README states the lab does not produce a working cluster (StretchCluster shows 'Waiting for controller', NodePools 'NotBound'), (3) strip the emojis from stretch-cluster/README.adoc (⏱️ line 26, ✅ lines 355-363, ❌ lines 369-375) if it ships at all, (4) fix the Title Case H2s in stretch-cluster/README.adoc, (5) rename the page-header-data attribute in docs/antora.yml to component-metadata to match docs #1698-#1705, rp-connect-docs redpanda-data/rp-connect-docs#427, and cloud-docs redpanda-data/cloud-docs#578 — docs-ui v3 helpers only read component-metadata, so as-is this PR will fall out of the unified sidebar.
2 participants
Summary
Updates component references across all Redpanda Labs examples to work with unified navigation component renames.
Changes
Why These Changes
Part of unified navigation rollout. Component names have been simplified:
Related PRs
Part of unified navigation implementation:
Jira
DOC-2180