Migrate website to Nextra v4

[FrancoKaddour]

Picks up #537.

Main changes:

• nextra 3 → 4, next 14 → 15, react 18 → 19
• Pages Router replaced by App Router — all MDX files moved to content/
• app/layout.tsx takes over what _app.tsx and _document.tsx were doing
• app/[[...mdxPath]]/page.tsx handles the catch-all MDX routing
• mdx-components.tsx added at root (required by v4)
• getHighlighter swapped for createHighlighter (Shiki v1 stable API)
• next.config.mjs: theme option removed (no longer supported in v4)
• src/index.tsx: updated to accept pageMap from getPageMap() instead of NextraThemeLayoutProps
• src/contexts/config.tsx: useRouter (next/router) → usePathname (next/navigation)
• src/components/head.tsx: next/head removed, meta tags moved to layout metadata

Still pending: replacing the custom FlexSearch with Pagefind's client integration. Happy to continue on that in a follow-up if useful.

[vercel]

@FrancoKaddour is attempting to deploy a commit to the David Sancho's projects Team on Vercel.

A member of the Team first needs to authorize it.

[davesnx]

I haven't checked nextra recently, but what's is the pagefind? 🤔

[FrancoKaddour]

Pagefind is a static search library that indexes the built HTML output and provides client-side search with no server required. Nextra v4 dropped the built-in FlexSearch integration, so pagefind is the recommended replacement — it runs as a postbuild step and generates the search index from .next/server/app.

That said, the client-side integration (the search UI component) is still pending — I noted it in the PR description. The postbuild script is there but the search won't be functional until that part is wired up. Happy to follow up on that in a separate PR if you want to keep this one focused on the migration itself.

[davesnx]

That's really nice, wanna do the search in a separate PR entirely?

[FrancoKaddour]

Absolutely, makes more sense to keep this PR focused on the migration. I'll open a follow-up for the Pagefind client integration once this lands.

[davesnx]

Looks good

[davesnx]

Thanks for taking the time, good update

[FrancoKaddour]

FYI — the CI failure is in demo/melange/build.mjs, which can't find the esbuild package. That's unrelated to the website migration — we didn't touch anything outside packages/website/. Might be a pre-existing issue with the demo build in CI.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
styled-ppx	Ignored	Preview	Jun 29, 2026 1:54pm