docs: redirect legacy cube.dev/docs URLs to new docs.cube.dev

[keydunov]

What

Sets up server-side 301 redirects from the old docs (cube.dev/docs) to the new Mintlify docs (docs.cube.dev).

The old Next.js/Nextra site stays deployed and issues cross-domain redirects so every legacy URL — and the many inbound links/SEO pointing at it — keeps resolving to the right page in the new docs.

Changes

• docs-mintlify/scripts/build_old_site_redirects.py — generator that reuses the existing PATH_REWRITES mapping (single source of truth, shared with rewrite_links.py/migrate_redirects.py) to produce the cross-domain redirect table from the old redirects.json. Re-runnable whenever the mapping or redirects.json changes.
• docs/redirects-new-docs.json — generated table of 509 redirects, first-match-wins order:
  • 455 specific page redirects (every legacy redirects.json entry, destination rewritten to the new structure) so consolidated/renamed pages reach their exact new home, e.g. /product/administration/workspace/saved-reports → https://docs.cube.dev/admin/workspace.
  • 54 wildcard prefix redirects (/product/configuration/:path* → …/docs/configuration/:path*, etc.) plus a /product/:path* catch-all for pages that never needed an explicit redirect.
• docs/next.config.mjs — imports the new table and points root / at https://docs.cube.dev/docs/introduction.

Reviewer notes

• basePath: false is intentionally omitted. Verified against the installed Next.js 16.1.6 (load-custom-routes.js): a redirect source gets the /docs basePath prefix unless basePath: false is set, while absolute https:// destinations are detected as external and never get basePath prepended. Omitting it makes sources match legacy /docs/... URLs while keeping cross-domain destinations intact. All 510 entries pass Next's own checkCustomRoutes validator.
• External passthroughs preserved: two legacy redirects to cube.dev/blog/... are left untouched (not rewritten to docs.cube.dev) — intentional.
• Deployment dependency: this relies on cube.dev/docs continuing to point at this old Vercel deployment so it can serve the redirects. Please confirm the old app stays live before/after the new docs cut over.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Jun 3, 2026, 2:14 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @keydunov's task in 2m 27s —— View job

---

Claude Code Review

Verdict: looks solid — 0 high, 2 medium, 3 low/nits

Tasks

• Read changed files
• Inspect rewrite_links.PATH_REWRITES reuse
• Validate generated redirects-new-docs.json (509 entries, no dup sources)
• Verify specific-vs-wildcard ordering and dedup
• Post review

---

Summary

The approach is clean: reuse PATH_REWRITES as a single source of truth, emit specific-first / wildcard-last, dedupe by source. Verified the generated table:

• 509 entries, zero duplicate sources (uniq -d empty).
• 455 specifics from redirects.json + 54 wildcards (one exact + one :path* per PATH_REWRITES entry + /product catch-all).
• 2 external passthroughs to cube.dev/blog/... preserved (intentional, per PR body).
• Specifics correctly win over wildcards — e.g. /product/administration/sso/okta keeps its consolidated …/saml destination instead of being grabbed by the SSO wildcard.

Medium

1. basePath is environment-conditional — docs/next.config.mjs:21 reads basePath: process.env.BASE_PATH || ''. Sources in redirects-new-docs.json are written as /product/... (no /docs prefix), so they only match legacy cube.dev/docs/product/... URLs when BASE_PATH=/docs is set at deploy time. Worth verifying that the Vercel project for the old site sets BASE_PATH=/docs (otherwise the redirects silently won't match in production). The reviewer note explains the absolute-destination interaction with basePath, but doesn't mention this prerequisite.

2. No catch-all for non-/product legacy roots — Old top-level URLs like /guides/..., /cohort-retention, /cube, /active-users etc. are present in redirects.json as specifics and carried forward, but there's no wildcard fallback for those prefixes. If a legacy /docs/guides/<page-not-in-redirects.json> URL is hit (or any of the ~30 non-/product/ top-level paths I spotted), it'll fall through to 404 on the old site rather than 301 to new docs. May be intentional (those pages never existed), but a deliberate /guides/:path* → /api-reference/recipes/:path* or similar fallback would be cheap insurance for the SEO-inbound case.

Low / nits

3. build_old_site_redirects.py:88-91 — the /product exact + /product/:path* catch-all is appended after iterating PATH_REWRITES. Since PATH_REWRITES doesn't include a /product mapping, this is fine, but the dedup loop will silently drop them if a /product entry ever appears in PATH_REWRITES later — worth a one-line comment to make that ordering invariant explicit.

4. build_old_site_redirects.py:55-62 — r.get("source", "") and r.get("destination", "") will produce a redirect with empty source: "" if the input is malformed. Cheap to add an assert source and destination so a bad redirects.json fails loud instead of emitting a garbage entry. Not a real risk today since the input is generated, but a small guard.

5. Generator output is checked into docs/redirects-new-docs.json (2547 lines). Consider a one-line Makefile target or npm script (yarn build:redirects) so reviewers don't need to remember the exact python build_old_site_redirects.py ... invocation when the source mapping changes. Optional.

Notes / praise

• The seen dedup pattern at build_old_site_redirects.py:126-132 is the right call — it makes specific-first / wildcard-last self-correcting even if both layers reference the same path.
• Module-level docstring is genuinely useful — explains the basePath: false decision and the two-layer model in one place.
• Reusing PATH_REWRITES from rewrite_links.py instead of forking the mapping is the right architectural choice.

• [`docs/old-to-new-redirects`](https://github.com/cube-js/cube/tree/docs/old-to-new-redirects)