Migrate documentation from Docusaurus to Mintlify#22
Conversation
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
0xrafasec
left a comment
0xrafasec
left a comment
There was a problem hiding this comment.
A few migration findings worth resolving on the preview deploy before merge. Content conversion itself looks faithful (diffed the low-similarity renames — purely frontmatter/admonition/link-rewrite churn, no prose drift). Comments inline.
| { "source": "/docs/api/:slug*", "destination": "/contracts/overview", "permanent": true }, | ||
| { "source": "/docs/api", "destination": "/contracts/overview", "permanent": true }, | ||
| { "source": "/docs/payment-api/:slug*", "destination": "/api-reference", "permanent": true }, | ||
| { "source": "/blog/:slug*", "destination": "/", "permanent": true }, |
There was a problem hiding this comment.
Blocking: this can shadow the live Blog tab. The new blog pages render at /blog/overview, /blog/oak-network-protocol-launch, etc. The old Docusaurus posts used slug: frontmatter, so their permalinks were identical (/blog/oak-network-protocol-launch, /blog/security-audit-complete, /blog/2026-roadmap-announcement). This /blog/:slug* → / source pattern therefore matches the live pages.
If Mintlify gives real pages precedence over redirects, fine — and old post URLs are preserved for free. If redirects fire first, every blog page 301s to the homepage and the Blog tab is dead. Please confirm on the preview deploy by clicking through /blog/*.
Separately, /blog → / (line 361) is a UX regression regardless — the old index should land on /blog/overview, not home. Suggest narrowing these to only the Docusaurus-generated paths that no longer exist (tag/author/pagination) rather than a blanket /blog/:slug*.
There was a problem hiding this comment.
Fixed. Both /blog/:slug* and /blog now redirect to /blog/overview instead of /.
On the shadowing concern: verified on the Mintlify preview (mint dev, which applies the docs.json redirects) that real pages take precedence over redirects. /blog/overview and all three posts return 200; only non-existent /blog/* paths (tags/authors/archive/pagination) follow the catch-all. The Blog tab is not shadowed. Kept the catch-all, now pointing at /blog/overview, since it routes every defunct blog URL to the index without risking 404s on unlisted paths.
| { "source": "/docs/operations/:slug*", "destination": "/operations/:slug*", "permanent": true }, | ||
| { "source": "/docs/api/:slug*", "destination": "/contracts/overview", "permanent": true }, | ||
| { "source": "/docs/api", "destination": "/contracts/overview", "permanent": true }, | ||
| { "source": "/docs/payment-api/:slug*", "destination": "/api-reference", "permanent": true }, |
There was a problem hiding this comment.
Verify this destination resolves. The API Reference tab is generated from OpenAPI via versions (no explicit slug), so I'm not confident Mintlify exposes a landing page at the bare /api-reference for a versioned OpenAPI tab — it may live under a version segment or a per-endpoint path. Please hit /api-reference on the preview; if it 404s, repoint this redirect at the actual generated landing route.
There was a problem hiding this comment.
No change was made here. Verified on the preview that /api-reference resolves: Mintlify redirects the tab root to the first generated endpoint, so /docs/payment-api/* -> /api-reference -> /api-reference/auth/user-sign-up returns 200. The single v1 version is the default and serves at the bare path with no version segment. /api-reference is also the stable target since the spec is auto-synced from crowdsplit, so hardcoding an endpoint slug would break on re-sync.
|
|
||
| ## Services | ||
|
|
||
| The SDK ships 15 service modules. Import the factory function for each service you need. |
There was a problem hiding this comment.
Count/table is inconsistent with the nav. This says "ships 15 service modules" and the table lists 15 rows, but the Payments SDK nav in docs.json also includes sdk/providers — a 16th service page that's absent from this table. Either bump the count and add a ProviderService row here, or drop sdk/providers from the nav.
There was a problem hiding this comment.
Fixed. sdk/providers.mdx documents a real createProviderService; sdk/overview.mdx was missing that service from the table. Bumped the count to 16 and added the ProviderService row. mint validate passes
2 participants
Summary
Moves the documentation site from Docusaurus to Mintlify. Content is preserved 1:1 (other than updating some outdated info), this changes the platform and tooling, not the docs themselves.
What's included
docs.jsondefines navigation, theme, SEO, and redirects.api-specs/v1/crowdsplits.yaml, kept current by thesync-payment-apiworkflow./docs/*routes redirect to their new paths viadocs.json.Removed
The Docusaurus toolchain is no longer needed:
docusaurus.config.ts,sidebars.ts,src/,package.json/pnpm-lock.yaml,tsconfig.json,vercel.json, and the Vercel deploy workflow. Mintlify builds with no local build step.Deployment
Hosting moves from Vercel to the Mintlify GitHub App. Before merging: connect the Mintlify app to this repo, point
docs.oaknetwork.orgat Mintlify, and add theCROWDSPLIT_RO_TOKENsecret used by the spec sync.