Docs site restructure to support ADP and Data Platform users

[JakeSCahill]

Adds a new architecture for the docs site to support two platforms: ADP and Data Platform

Related PRs

Extension & UI

• Add unified navigation extension and update component references docs-extensions-and-macros#197 - Unified navigation extension
• Docs site restructure v3 docs-ui#376 - Unified navigation UI

Content Repositories

• Add page-header-data for unified navigation docs#1697 - page-header-data (main)
• Rename ROOT component to streaming (v24.3) docs#1698-1704 - Version branch renames
• Update Cloud docs landing page to component-home-v3 cloud-docs#578 - Component home v3
• Add unified navigation attributes and rename component rp-connect-docs#427 - Unified navigation attributes

Testing Coverage

This playbook enables testing of:

• ✅ Unified sidebar with multiple buckets (Streaming, Connect)
• ✅ Component theming (colors, icons)
• ✅ Per-bucket version selectors
• ✅ Bucket expand/collapse
• ✅ Component home v3 layouts
• ✅ Data Platform landing page
• ✅ All 7 renamed version branches
• ✅ Product switcher with umbrella hierarchy
• ✅ Navigation aggregation from child components

[netlify]

✅ Deploy Preview for redpanda-documentation ready!

Name	Link
🔨 Latest commit	079baff
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-documentation/deploys/6a10028940197c00088fd405
😎 Deploy Preview	https://deploy-preview-173--redpanda-documentation.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[JakeSCahill]

Jira: DOC-2180

[Feediver1]

https://deploy-preview-173--redpanda-documentation.netlify.app/data-platform/
I don't think the tile with Connect Postgres CDC to Snowflake is linking to the correct page. Instead of taking users to https://deploy-preview-173--redpanda-documentation.netlify.app/connect/get-started/quickstarts/, shouldn't it go to https://deploy-preview-173--redpanda-documentation.netlify.app/connect/components/inputs/postgres_cdc/ or some Iceberg page? Also, I believe it is PostgreSQL not Postgres, no?

[Feediver1]

https://deploy-preview-173--redpanda-documentation.netlify.app/connect/get-started/quickstarts/
I see a dash before the Bloblang Playground heading on right sidenav under Connect Tools. Why? Is this a typo?

[Feediver1]

Can you shape these buttons more similarly?

Why @micheleRP?

[Feediver1]

I think I'd like to remove all text from this dropdown. I don't think it adds anything

Not sure I agree. Remember that our new org model might not make sense to people who have been using our docs all along. The new Streaming category comes to mind--this little text may help them.

[micheleRP]

Can you shape these buttons more similarly?

Why @micheleRP?

because they look and feel different

[micheleRP]

If the home page defaults to this on May 22 (and ADP doesn't come until June 15), do we want to include the Overview and MCP Server links somehow? Or just wait?

[JakeSCahill]

https://deploy-preview-173--redpanda-documentation.netlify.app/connect/get-started/quickstarts/ I see a dash before the Bloblang Playground heading on right sidenav under Connect Tools. Why? Is this a typo?

that's an icon. It's meant to represent a terminal prompt.

[JakeSCahill]

This NEW card for SQL has the green Self-Managed color wrap. The NEW in green also gives Self-Managed. Suggest using the Data Platform purple for both NEW button and card wrap.
Also: what do you think about adding cards under this What's new to both the Cloud & the SM What's New pages?

To add - how does the What's New card on the landing pages get populated? And how many items? I'm assuming that the SM home/landing page doesn't have one because we just didn't pick one?

I also noticed that the card has a slightly different placement on the Data Platform home vs Cloud home. (Maybe it's my window size?) In Cloud, it has more padding around it and is closer to the BYOC/Serverless options, and in Data Platform it's flush all the way to the upper right boundary. But either way the What's new card feels a bit disjointed and out of place from the rest of the elements on the landing page

I'd like to create a system here we define all what's new content in partials with certain pre-defined metadata and this is used to populate both the what's new pages and the landing pages. We could have a strict number displayed on the landing pages or make it scrollable/a carousel.

Noted on the landing page style for what's new. I'm working on a fix for that.

[micheleRP]

Review

Critical

1. antora-playbook.yml:92-94 — production points redpanda-labs at branches: main, but main still has name: redpanda-labs. This PR's extensions (generate-index-data:369, replace-attributes-in-attachments:411) and meta-docs/CONTRIBUTING.adoc use component: labs. Build will not find a labs component. Local + preview playbooks already use feature/page-header-data (which has name: labs); production needs the same swap or the rename has to land on redpanda-labs/main first.

2. package.json:20 — "@redpanda-data/docs-extensions-and-macros": "github:...#feature/unified-navigation". Pinning to a feature branch means a force-push will break prod. Must swap to a tagged release before the relaunch.

3. home/modules/ROOT/pages/index.adoc:42 — broken xref: :page-cloud-docs: cloud-data-platform:ROOT:index.adoc. On feature/component-home-v3 the start page is home:index.adoc (verified — ROOT/pages/index.adoc returns 404). Fix to: cloud-data-platform:home:index.adoc. (Line 48's agentic-data-plane:ROOT:index.adoc is fine — that component's start page is ROOT:index.adoc.)

4. self-managed/modules/ROOT/pages/index.adoc:20,24 — broken xrefs:

   • streaming:deploy:deployment-option/self-hosted/kubernetes/index.adoc
   • streaming:deploy:deployment-option/self-hosted/manual/index.adoc

   On feature/rename-streaming-main, the actual paths are deploy:redpanda/kubernetes/index.adoc and deploy:redpanda/manual/index.adoc (verified via GitHub API; no page-aliases on the kubernetes index covers the old path).

5. self-managed/modules/ROOT/pages/index.adoc:5 — em dash violation in :page-hero-description: (infrastructure—whether on bare metal...). Strip per Redpanda style. Suggested: replace with comma.

6. INTERIM-HOME-PAGE.md ships in the PR root with content like "TEMPORARY", "Why this change?", "When to revert?". Internal handoff note — should not live at repo root in a public docs site repo. Delete or move to meta-docs/ with a clear WIP prefix. Also contradicts antora-playbook.yml:3 (start_page: home:ROOT:index.adoc) — only test-unified-nav.yml uses data-platform::index.adoc.

7. test-unified-nav.yml ships with hardcoded /Users/jakecahill/Documents/... paths (lines 22, 42, 46, 50, 55, 60). Personal dev playbook; delete before merge.

8. local-antora-playbook.yml:47, 55 — hardcoded /Users/jakecahill/Documents/rp-connect-docs and /Users/jakecahill/Documents/docs-ui/build/ui-bundle.zip. Other contributors can't use this. Replace with the GitHub URLs the preview playbook uses.

Suggestions

1. netlify/edge-functions/skill-search-docs.ts:23 — still points to https://docs.redpanda.com/current/home/; should be /streaming/home/ (the file already migrated the cloud/connect/labs sections).
2. home/modules/ROOT/pages/llms.adoc — mixed migration: paths like /current/get-started/quickstarts.md, /current/deploy.md, /current/reference/rpk/..., /current/console.md, /current/troubleshoot.md (lines 35, 49, 57–58, 62, 70, 75–76, 90–93, 97–98, 103) still reference current while sibling sections moved to cloud-data-platform, connect, labs. Finish the rename or file a follow-up.
3. netlify.toml:16 — Lighthouse plugin audits current/home/index.html; will 404 after rename.
4. netlify.toml:62-80 — markdown URL aliases still use /redpanda-cloud.md, /redpanda-connect.md, /redpanda-labs.md. Add new aliases (/cloud-data-platform.md, /connect.md, /labs.md) and keep the old ones as redirects.
5. netlify.toml:112-114 — /home → /data-platform/ 301 looks like the INTERIM behavior. Confirm whether home is actually the production home.
6. netlify.toml:354-501 — every bulk redirect target still writes to /redpanda-cloud/, /redpanda-connect/, /redpanda-labs/. After the rename those targets 404. Probably deferrable to a follow-up PR, but flag it.

Coordination risk

Verified all referenced feature branches exist and component names match the playbook references:

• docs/feature/rename-streaming-main → name: streaming ✓
• cloud-docs/feature/component-home-v3 → name: cloud-data-platform ✓ (but start_page: home:index.adoc, not ROOT:index.adoc — see Critical #3)
• rp-connect-docs/feature/unified-navigation → name: connect ✓
• adp-docs/feature/platform-badges → name: agentic-data-plane ✓
• redpanda-labs/main → still name: redpanda-labs ✗ (see Critical #1)
• All 7 feature/rename-streaming-23.3 … 25.3 branches exist
• UI bundle v3.0.0-beta.10 exists

Nothing pins to a released version — every source is on a moving feature branch. Acceptable while staging the relaunch, but the 14 PRs must merge in lockstep, and package.json:20 plus the redpanda-labs branch ref need to be the last things switched.

---

Cross-rollout notes (applies to all 14 PRs in the docs.redpanda.com relaunch)

Posting these here rather than fragmenting across all 14 PRs.

Suggested approval / merge order

The 14 PRs must merge in a tight window, but within that window order matters because component renames invalidate xref targets.

1. First (independent, ready): docs redpanda-data/docs#1698-redpanda-data/docs#1704 — version-branch renames. No new content beyond antora.yml rewrites and xref sweeps.
2. Then (small fixes): docs-extensions-and-macros redpanda-data/docs-extensions-and-macros#197, after applying the 2 critical fixes.
3. Then (with verifications): docs redpanda-data/docs#1705, cloud-docs redpanda-data/cloud-docs#578, rp-connect-docs redpanda-data/rp-connect-docs#427 — after the fix-and-confirm cycles.
4. Then (after coordination fixes): redpanda-labs redpanda-data/redpanda-labs#285 — after the page-header-data → component-metadata rename and removal of the unfinished kubernetes/stretch-cluster lab.
5. Then: docs-site #173 — after the critical fixes above (especially the package.json unpin and the redpanda-labs branch reference).
6. Last: docs-ui redpanda-data/docs-ui#376 — after the major rework pass. UI bundle should pin to a tagged release (v3.0.0-beta.10 or later), and the hardcoded component names should either have fallbacks or be the final hard switch.

Verification (cheap end-to-end checks before / during merge)

1. {product-name} resolution (referenced by docs redpanda-data/docs#1705 and redpanda-data/docs#1698):

   cd /Users/miche/projects/docs && git checkout feature/rename-streaming-main && npm run build
   

   If {product-name} renders as literal {product-name}, the production playbook needs to aggregate shared into streaming.

2. Cloud landing page schema (cloud-docs redpanda-data/cloud-docs#578): open the Netlify deploy preview. Confirm the Choose your component and Choose your deployment blocks render (they should, per the component-home-v3 partial which supports :page-component-N-*: and :page-deployment-N-*: attrs).

3. docs-ui redpanda-data/docs-ui#376 CSS lint — cd /Users/miche/projects/docs-ui && gulp bundle. If lint fails on the keyframes / color-mix(in sRGB,...) etc., Critical #2 is real.

4. docs-ui redpanda-data/docs-ui#376 empty-dropdown bug — local preview with a component at default version and >1 version available. If the chevron renders but the menu has no items, Critical #4 is real.

Cross-PR coordination items (separate bucket from per-PR critical)

These don't break any single PR on its own merits, but they will break the coordinated cutover if not aligned before the merge window:

1. Attribute key inconsistency. Every renamed component sets new metadata in its antora.yml, but the attribute key differs:

   • component-metadata — docs redpanda-data/docs#1698-redpanda-data/docs#1705, rp-connect-docs redpanda-data/rp-connect-docs#427, cloud-docs redpanda-data/cloud-docs#578
   • page-header-data — redpanda-labs redpanda-data/redpanda-labs#285 (outlier)

   The docs-ui v3 helpers read component-metadata. If the labs PR ships as-is, labs likely falls out of the sidebar or renders with stale metadata. Pick component-metadata and update labs to match.

2. redpanda-labs rename branch ordering. This playbook points redpanda-labs at branches: main, but main still has name: redpanda-labs. The new extensions and meta-docs/CONTRIBUTING.adoc already use component: labs. The labs PR must either merge into main first, OR this playbook must point at the feature branch.

3. docs-ui redpanda-data/docs-ui#376 hardcoded component names with no fallback. Despite the PR body's "fallback logic" claim, several helpers/partials flip to the new name with no || fallback. Either restore real fallbacks, or commit to merging the rename PRs strictly before the UI bundle deploys.

4. {product-name} attribute is used heavily in docs redpanda-data/docs#1705 + redpanda-data/docs#1698 but is defined only on the docs shared branch (Redpanda Streaming). Confirm the production playbook still aggregates shared into the renamed streaming component, or every {product-name} will render as literal.

5. Feature-branch pinning in package.json:20. Extensions pinned to github:...#feature/unified-navigation. A force-push on that branch breaks production. Swap to a tagged release before merging.

6. Stale local-antora-playbook.yml start_page: in two repos.

   • rp-connect-docs: start_page: redpanda-connect:home:index.adoc (component is now connect)
   • redpanda-labs: start_page: redpanda-labs:ROOT:index.adoc (component is now labs)

   Local dev builds will fail on both until fixed.

7. PR redpanda-data/docs#1697 ("Add page-header-data for unified navigation") is closed, never merged (closed 2026-05-12). Its work has been folded into redpanda-data/docs#1705. Multiple sibling PRs still reference redpanda-data/docs#1697 in their bodies — Jake can either delete those references or note "superseded by redpanda-data/docs#1705."

Michele's existing inline comments on this PR

All 5 of her suggested edits already appear to be applied in the current PR head:

• :page-deploy-2-desc: in self-managed/.../index.adoc:13 matches her wording
• :page-hero-stat2-number: 300+ in data-platform/.../index.adoc:10 matches
• 300+ connectors for sources and destinations in skill-search-docs.ts:42 matches
• :page-cloud-description: ... Serverless, Dedicated, or Bring Your Own Cloud (BYOC). in data-platform/.../index.adoc:34 matches
• :page-cloud-stat1-text: SLA on BYOC & Dedicated in data-platform/.../index.adoc:39 matches

Safe to resolve all 5 on GitHub.

[micheleRP]

Approved on the assumption that all 8 Critical items in the review comment above are addressed before merge: delete INTERIM-HOME-PAGE.md + test-unified-nav.yml, unpin package.json:20 from the feature branch, repoint redpanda-labs in the playbook, fix the 3 broken xrefs (cloud-data-platform:ROOT:index.adoc → :home:; the two streaming:deploy:deployment-option/self-hosted/... paths), strip the em dash in the self-managed hero description, replace the /Users/jakecahill/... paths in local-antora-playbook.yml. Cross-rollout notes (merge order, verification, coordination items) are appended to the comment for your reference.