feat(docs): upgrade to Nextra 4 - #106
Merged
Merged
Conversation
Nextra 4 drops the Pages Router, so the docs site moves to the App Router with the content directory convention. - `pages/` -> `content/`, served through `app/[[...mdxPath]]/page.tsx` - section pages (`array.mdx`) -> folder index pages (`array/index.mdx`) with `asIndexPage: true`, so each section stays a single sidebar entry - `_meta.json` -> `_meta.ts` - `theme.config.jsx` -> `<Layout>`/`<Navbar>`/`<Footer>`/`<Head>` props in `app/layout.tsx`, plus Next's `metadata` export for SEO tags - search moves from FlexSearch to Pagefind via a `postbuild` script - `next export` -> `output: 'export'`, so `npm run build` produces `out/` - Next 13 -> 15, React 18 -> 19, Tailwind 3 -> 4 - `TOC` uses `Cards` from `nextra/components` - global.css drops the dead `nx-`-prefixed overrides; the background and primary colors now come from `<Head>` The navbar logo uses a `<span>` instead of an `<h1>`: Pagefind takes a page's first `<h1>` as its search result title, and the navbar one made every result read "Toolbox". zod is pinned below 4.4 because Nextra 4.6.1's `<Layout>` rejects its own `children` prop when validating against newer zod, which fails every page render (shuding/nextra#4989). Closes #81 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ASafaeirad
force-pushed
the
feat/nextra-4
branch
from
September 10, 2026 13:27
79e6619 to
d78d851
Compare
|
🎉 This PR is included in version 4.25.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #81
Nextra 4 drops the Pages Router entirely, so this is a structural migration rather than a version bump. URLs are unchanged (
/array,/array/compact, …).Routing / content
docs/pages/→docs/content/, rendered throughapp/[[...mdxPath]]/page.tsx+mdx-components.tsarray.mdx) became folder index pages (array/index.mdx) withasIndexPage: truefront matter. Without that flag Nextra 4 renders each section twice in the sidebar — once as a folder toggle, once as a link._meta.json→_meta.tsTheme
theme.config.jsxis gone; its options are now props on<Layout>/<Navbar>/<Footer>/<Head>inapp/layout.tsx, plus Next'smetadataexport for the SEO tagsglobal.cssis gone too — it was entirelynx--prefixed class hacks that no longer exist. The background (rgb(35,37,46)) and primary hue (31) come from<Head>now; only the card border/radius tweak survives, inapp/globals.css.Build
next export→output: 'export'postbuildscriptgithub-pages.ymlrunsnpm run build, and usesfetch-depth: 0so Nextra can read git history for per-page last-updated datesTwo things worth a look
zod is pinned to
4.3.6viaoverrides. Nextra 4.6.1's<Layout>stripschildrenbefore validating its props, but zod >= 4.4 made that key non-optional, so every page render throws. This is shuding/nextra#4989, unfixed in a release. The override can go once upstream ships a fix.The navbar logo is a
<span>instead of an<h1>. Pagefind uses a page's first<h1>as the search-result title, so with the old markup every search result was titled "Toolbox". Computed styles are identical — Tailwind preflight already reset it to 16px/400.One behaviour change
The
/nodesidebar label now reads "Env" rather than "Node". Nextra 4 takes a section's label from its index page title, and that page's heading is# Env. Addingnode: 'Node'tocontent/_meta.tsrestores the old label if you'd prefer it.Verification
vp check,vp run type-checkandvp test(600 tests) all pass. The docs build produces 106 static pages with Pagefind indexing 105.I served
out/and confirmed in-browser: dark theme forced with no flash, hue-31 accent, 12 cards on/arraywith the custom border, sidebar collapsed to level 1, syntax highlighting, copy buttons, the "Suggest a new function" link still pointing at the proposal issue template, edit links resolving toblob/main/docs/content/…, and Pagefind returning correct titles and URLs.🤖 Generated with Claude Code