DOC-1292 Move Migrate section to the top level in nav tree

[JakeSCahill]

Description

Resolves https://redpandadata.atlassian.net/browse/DOC-1292
Review deadline: May 7

This pull request reorganizes and simplifies the migration documentation by moving migration-related files to a new migrate directory, updating references across the codebase, and adding aliases for backward compatibility. The changes aim to improve the structure and clarity of the documentation.

Page previews

Checks

• New feature
• Content gap
• Support Follow-up
• Small fix (typos, links, copyedits, etc)

[coderabbitai]

📝 Walkthrough

Walkthrough

The documentation navigation was restructured by moving the "Migrate" section from under the "Upgrade" hierarchy to a top-level position in the navigation tree. All related cross-reference links throughout the documentation were updated to reflect the new path for migration documents. Page alias metadata was added to the migration documents to support backward compatibility with old paths. The navigation structure and document references now consistently use the new top-level "migrate" path, and the operator-specific migration entry was removed from the navigation. No changes were made to exported or public code entities.

Assessment against linked issues

Objective (Issue)	Addressed	Explanation
Move Migrate tasks to a top-level in the nav tree (DOC-1292)	✅

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	e8a8b1f
🔍 Latest deploy log	https://app.netlify.com/sites/redpanda-docs-preview/deploys/6819bed547c4960008ac847e
😎 Deploy Preview	https://deploy-preview-1108--redpanda-docs-preview.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 site configuration.

[coderabbitai]

Actionable comments posted: 1

🔭 Outside diff range comments (1)

modules/upgrade/pages/deprecated/index.adoc (1)

4-4: ⚠️ Potential issue

Verify :page-aliases: entry for Kubernetes operator migration
The alias upgrade:migrate/kubernetes/operator.adoc doesn’t match any known file in the migrate/kubernetes directory (we expect helm-to-operator.adoc or strimzi.adoc). This may lead to broken links. Please confirm or correct this alias.

🧹 Nitpick comments (1)

modules/get-started/pages/release-notes/redpanda.adoc (1)

57-57: Cross-reference updated to top-level migrate path
The xref: was correctly switched from upgrade:migrate/console-v3.adoc[] to migrate:console-v3.adoc[].

Consider adding descriptive link text instead of an empty bracket for improved clarity, e.g.:

*Action required*: xref:migrate:console-v3.adoc[Console v3 migration guide].

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0e49b34 and e8a8b1f.

📒 Files selected for processing (14)

• modules/ROOT/nav.adoc (1 hunks)
• modules/deploy/pages/deployment-option/self-hosted/kubernetes/k-deployment-overview.adoc (1 hunks)
• modules/deploy/pages/deployment-option/self-hosted/manual/production/production-readiness.adoc (2 hunks)
• modules/get-started/pages/release-notes/redpanda.adoc (1 hunks)
• modules/manage/partials/whole-cluster-restore.adoc (1 hunks)
• modules/migrate/pages/console-v3.adoc (1 hunks)
• modules/migrate/pages/data-migration.adoc (1 hunks)
• modules/migrate/pages/index.adoc (1 hunks)
• modules/migrate/pages/kubernetes/helm-to-operator.adoc (1 hunks)
• modules/migrate/pages/kubernetes/strimzi.adoc (1 hunks)
• modules/shared/partials/operator-deprecation-notice.adoc (1 hunks)
• modules/upgrade/pages/deprecated/index.adoc (1 hunks)
• modules/upgrade/pages/rolling-upgrade.adoc (1 hunks)
• modules/upgrade/partials/incompat-changes.adoc (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (3)

• GitHub Check: Redirect rules - redpanda-docs-preview
• GitHub Check: Header rules - redpanda-docs-preview
• GitHub Check: Pages changed - redpanda-docs-preview

🔇 Additional comments (12)

modules/migrate/pages/console-v3.adoc (1)

4-4: Alias addition for backward compatibility is correct.
The new :page-aliases: entry ensures existing links under upgrade:migrate/console-v3.adoc continue to resolve to this page.

modules/migrate/pages/kubernetes/strimzi.adoc (1)

3-3: Backward-compatibility alias is accurate.
Adding :page-aliases: upgrade:migrate/kubernetes/strimzi.adoc maintains existing URLs without altering content.

modules/shared/partials/operator-deprecation-notice.adoc (1)

3-3: Deprecation notice simplified appropriately.
The updated line cleanly removes migration guidance and correctly points readers to the deprecation notice under upgrade:deprecated/cluster-resource.adoc.

modules/migrate/pages/kubernetes/helm-to-operator.adoc (1)

5-5: Page alias for legacy path is correct.
The :page-aliases: upgrade:migrate/kubernetes/helm-to-operator.adoc attribute maintains backward compatibility without impacting existing content.

modules/upgrade/partials/incompat-changes.adoc (1)

3-3: Cross-reference updated to new migrate path.
Switching from xref:upgrade:migrate/console-v3.adoc to xref:migrate:console-v3.adoc aligns with the restructured navigation and page aliases.

modules/migrate/pages/index.adoc (1)

4-4: Backward-compatibility alias correctly applied
The new :page-aliases: entry ensures that references to upgrade:migrate/index.adoc will resolve to this page, preserving existing links. Syntax and path look correct.

modules/migrate/pages/data-migration.adoc (1)

3-3: Page alias for upgrade path added
Including upgrade:migrate/data-migration.adoc alias maintains backward-compatibility for existing links. The comma-separated list is syntactically correct.

modules/deploy/pages/deployment-option/self-hosted/kubernetes/k-deployment-overview.adoc (1)

48-48: Migration link updated for Helm-Operator guide
The cross-reference was correctly updated from upgrade:migrate/... to xref:migrate:kubernetes/helm-to-operator.adoc[Migrate from the Redpanda Helm chart], preserving clear link text.

modules/upgrade/pages/deprecated/index.adoc (1)

272-272: Cross-reference to console migration guide updated
The xref: was correctly changed to migrate:console-v3.adoc[], ensuring links point to the new top-level migration guide.

modules/upgrade/pages/rolling-upgrade.adoc (1)

110-110:

✅ Verification successful

Correct cross-reference to top-level migrate path
This update replaces the nested upgrade:migrate link with xref:migrate:console-v3.adoc. Please confirm that modules/migrate/pages/console-v3.adoc includes the old upgrade:migrate/console-v3.adoc as an alias (:page-aliases:) for backward compatibility.

---

🏁 Script executed:

#!/bin/bash
# Verify no stale upgrade:migrate console-v3 references
rg -n "upgrade:migrate/console-v3.adoc"

Length of output: 126

---

Verified alias and approved cross-reference update
modules/migrate/pages/console-v3.adoc includes :page-aliases: upgrade:migrate/console-v3.adoc on line 4, ensuring backward compatibility for the updated xref:migrate:console-v3.adoc link. No further changes needed.

modules/manage/partials/whole-cluster-restore.adoc (1)

15-15:

✅ Verification successful

Correct MirrorMaker 2 migration link to top-level migrate
The xref:migrate:data-migration.adoc[MirrorMaker 2] link now aligns with the relocated section. Please verify that modules/migrate/pages/data-migration.adoc includes an alias for the legacy upgrade:migrate/data-migration.adoc path.

---

🏁 Script executed:

#!/bin/bash
# Check alias metadata in the migrate data-migration page
rg -n "page-aliases.*data-migration.adoc" modules/migrate/pages/data-migration.adoc

Length of output: 203

---

MirrorMaker 2 link and alias verified
The xref:migrate:data-migration.adoc[MirrorMaker 2] reference is correct, and I’ve confirmed that modules/migrate/pages/data-migration.adoc includes the legacy alias upgrade:migrate/data-migration.adoc. LGTM.

modules/ROOT/nav.adoc (1)

96-100:

✅ Verification successful

Promote 'Migrate' to root-level in navigation
The new * xref:migrate:index.adoc[Migrate] section correctly replaces the former nested upgrade:migrate subsection, and the operator migration entry has been removed. Ensure modules/migrate/pages/index.adoc contains alias metadata for the old upgrade:migrate/index.adoc path and that there are no lingering upgrade:migrate references in the nav.

---

🏁 Script executed:

#!/bin/bash
# Confirm no stale upgrade:migrate entries in navigation
rg -n "upgrade:migrate" modules/ROOT/nav.adoc

Length of output: 45

---

🏁 Script executed:

#!/bin/bash
# Check for any lingering “upgrade:migrate” references across the entire repo
rg -n "upgrade:migrate" .

# Verify alias metadata exists in the new migrate index page
rg -n ":aliases:" -A 3 modules/migrate/pages/index.adoc

Length of output: 900

---

Promote 'Migrate' to root-level in navigation: Verified

• modules/ROOT/nav.adoc contains no lingering upgrade:migrate references.
• modules/migrate/pages/index.adoc includes the required alias metadata (:page-aliases: upgrade:migrate/index.adoc on line 4).

All checks pass—LGTM.

[Feediver1]

lgtm