Redirect legacy /docs/* and /api/* URLs to Mintlify#1607
Conversation
Redirect all old Fumadocs /docs/* and /api/* URLs to their new Mintlify equivalents via the docs.json redirects array: - 87 /docs/* content-page redirects (guides, sdk, components, etc.), with components -> /sdk/overview and the removed customization section -> /. - 171 generated /api/* REST-reference redirects (client/server/webhooks), produced by scripts/generate-api-redirects.mjs from the frozen legacy URL snapshot joined against the live OpenAPI specs. - A single /api/admin/:slug* wildcard -> /api/overview (admin is hidden in the new docs, so no per-endpoint pages exist).
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds a Node.js script ( ChangesLegacy API Redirect Generator
Sequence Diagram(s)Sequence diagram provided in hidden review stack above showing the script's data flow from snapshot and live OpenAPI specs through index building and redirect generation to docs.json output. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs-mintlify/scripts/generate-api-redirects.mjs`:
- Around line 133-143: The --check mode should fail when unresolved operations
are being downgraded to the overview fallback. Currently, the code only warns
about unresolved operations in the fellBack array but continues even when check
mode is enabled. Add a condition in the check block that exits with error code 1
if fellBack.length is greater than zero, ensuring the process fails when
endpoint-accurate redirects cannot be generated and broad fallbacks would be
used instead.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d7f13045-bc99-4757-9db5-b1a99492348b
📒 Files selected for processing (4)
docs-mintlify/docs.jsondocs-mintlify/package.jsondocs-mintlify/scripts/generate-api-redirects.mjsdocs-mintlify/scripts/legacy-api-redirects.snapshot.json
Greptile SummaryThis PR adds 266 redirects to
Confidence Score: 4/5Safe to merge — this is a docs-only config change with no application code impact; the worst case for any redirect misconfiguration is a stale external link landing on the wrong docs page. The hand-written /docs/* redirects and the generated /api/client+server/* redirects are well-structured and verified. Two edge cases in the generator (empty summary producing a malformed destination URL without a fallback warning, and webhook destinations being frozen rather than spec-derived) are low-probability in practice but could silently misdirect users if they ever trigger. docs-mintlify/scripts/generate-api-redirects.mjs — the empty-summary edge case and the webhook destination construction logic are the two spots worth a second read. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Legacy URL] --> B{Path prefix?}
B -->|/docs/*| C[Hand-written redirect]
B -->|/api/admin/*| D[Wildcard to api/overview]
B -->|/api/client or server| E[Generated redirect]
B -->|/api/webhooks/*| F[Generated webhook redirect]
C --> G[New Mintlify page]
E --> H{Op in live spec?}
H -->|Yes| I[Kebab tag and summary slug]
H -->|No| J[Falls back to api/overview]
F --> K[Strip dots from legacy slug]
K --> L[New webhook page]
subgraph Generator
E
F
H
I
J
K
L
end
subgraph Snapshot
M[Frozen old URLs plus op keys]
end
Snapshot --> Generator
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A[Legacy URL] --> B{Path prefix?}
B -->|/docs/*| C[Hand-written redirect]
B -->|/api/admin/*| D[Wildcard to api/overview]
B -->|/api/client or server| E[Generated redirect]
B -->|/api/webhooks/*| F[Generated webhook redirect]
C --> G[New Mintlify page]
E --> H{Op in live spec?}
H -->|Yes| I[Kebab tag and summary slug]
H -->|No| J[Falls back to api/overview]
F --> K[Strip dots from legacy slug]
K --> L[New webhook page]
subgraph Generator
E
F
H
I
J
K
L
end
subgraph Snapshot
M[Frozen old URLs plus op keys]
end
Snapshot --> Generator
Prompt To Fix All With AIFix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
docs-mintlify/scripts/generate-api-redirects.mjs:73-76
**Empty summary/operationId silently produces a malformed destination URL**
When `op.summary` is an empty string AND `op.operationId` is also absent/empty, `kebab('')` returns `''` and the entry is stored in the Map as `/api/${group}/${kebab(tag)}/` (empty trailing segment). A snapshot lookup that hits this entry will resolve to that malformed URL instead of falling back to `OVERVIEW` — `destination` is non-undefined so `fellBack` is never populated. This means such an operation would produce a redirect to a page that doesn't exist with no warning. Real-world OpenAPI specs almost always have either a summary or operationId, but an explicit guard (e.g., `if (!kebab(summary)) { ... }`) would make the fallback reliable.
### Issue 2 of 2
docs-mintlify/scripts/generate-api-redirects.mjs:83-88
**Webhook destinations are frozen, not derived from the live spec**
Unlike client/server redirects (which are re-derived from the live OpenAPI spec on each run so they track renames), webhook destinations are constructed by stripping dots from the legacy source URL. If Mintlify changes how it slugifies webhook event pages (e.g., switches to kebab-case with a hyphen instead of collapsing to `team_membershipcreated`), these 10 redirects would silently point to 404s with no generator warning. Since the generator is described as keeping targets "correct as the specs evolve," it is worth noting this gap for future maintainers — or adding a `--check` assertion that at least validates the destinations against the live `mint dev` in CI.
Reviews (1): Last reviewed commit: "Add legacy docs redirects to Mintlify" | Re-trigger Greptile |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
- --check now fails when any snapshot op degrades to /api/overview, so
snapshot/spec drift can't silently ship broad fallback redirects.
- Skip indexing operations with an empty tag or summary slug so they fall
back to the overview instead of producing a malformed /api/{group}/{tag}/ URL.
- Document that webhook destinations are derived from the frozen legacy URL
(not re-derived from the live spec) and how to re-verify if Mintlify's
webhook slug rule changes.
There was a problem hiding this comment.
instead of this (which we'll have to maintain forever), can we keep an equivalent list in the original docs app, and just make that app only redirect, directly to the correct mintlify docs pages?
N2D4
left a comment
N2D4
left a comment
There was a problem hiding this comment.
we should update the old docs to redirect to docs-mintlify, otherwise we'll forever be stuck with an insane amount of redirect URLs to maintain
|
check #1620 It contains this, and keeps a old docs app alive on vercel, with auto-redirects. It also handles these issues remaining: I talked with the guys at 2027 and here is what they had to say:
I believe this is a big larger than just redirects |
3 participants
What
Adds redirects from every legacy Fumadocs URL (
docs.stack-auth.com/docs/*and/api/*) to its new Mintlify equivalent, so old deep links don't 404 after the docs migration. Config-only on the Mintlify side — all redirects live indocs-mintlify/docs.json(the canonical place perAGENTS.md).How it maps
/docs/*content pages (87 redirects) — every old content URL is covered (verified by diffing the old app'ssitemap.xml). Notable judgment calls:/sdk/overview//guides/*,/sdk/*, or/api/overviewpage./api/*REST reference (171 generated + 1 wildcard) — the old Fumadocs and new Mintlify sites use different slug schemes, but both derive deterministically from the same OpenAPI specs. Rather than hand-list 271 brittle entries:scripts/generate-api-redirects.mjscomputes each new slug from the live specs (/api/{group}/{kebab(tag)}/{kebab(summary)}for client/server; dot-stripped event name for webhooks) and joins it to the frozen legacy URL list inscripts/legacy-api-redirects.snapshot.json. It surgically rewrites only the/api/(client|server|webhooks)/*block indocs.json, leaving the rest of the file untouched, and is idempotent./api/admin/:slug*→/api/overviewwildcard.The snapshot is intentionally frozen (the old app is being retired); its provenance is documented in the generator header so it's reproducible from git history.
Verification
mint dev.200.mint validatepasses; no duplicate sources; generator is idempotent (--checkclean).Follow-ups (NOT in this PR)
docs.stack-auth.com/*→docs.hexclave.com/*as a path-preserving 301 (infra/DNS, not this repo). Required as the first hop — Mintlify's path redirects fire after it. A redirect that drops the path would defeat these mappings.generate-api-redirectsinto the rootcodegenchain so the existing "uncommitted changes" check catches stale/api/*targets. Deferred per discussion.docs/-folder removal will need to clean up its CI references (cp docs/.env.development …) and thegenerate-openapi-docs:watchdev script — unrelated to this PR.Summary by cubic
Redirect all legacy Fumadocs URLs under /docs/* and /api/* to their new Mintlify pages so old deep links keep working. Adds 266 redirects and a generator for the
/api/*routes.New Features
docs-mintlify/docs.jsoncovering all legacy/docs/*pages and REST reference; components →/sdk/overview, customization →/, plus/api/admin/:slug*→/api/overview.docs-mintlify/scripts/generate-api-redirects.mjsto compute 171/api/(client|server|webhooks)/*targets from live OpenAPI specs and a frozen legacy snapshot; idempotent, only updates managed entries, skips malformed slugs, and--checknow fails if any snapshot op degrades to/api/overview. Webhook targets are derived from the legacy URL format (documented in script).generate-api-redirectsnpm script indocs-mintlify/package.json.Migration
docs.stack-auth.com/*→docs.hexclave.com/*so Mintlify path redirects apply.Written for commit bdc5a8b. Summary will update on new commits.
Summary by CodeRabbit
/api/*and related routes now automatically navigate to the latest documentation locations.