unstale

npm / nextra-theme-docs

nextra-theme-docs

What changed in nextra-theme-docs 3 to 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-23.

102 breaking37 new APIs and options5 performance13 behavior and defaults1 tooling3 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.4 on npm

nextra-theme-docs 4112 changes

Breaking changes 74

  • Nextra 4 exclusively uses the Next.js App Router; Pages Router support has been discontinued.

    4.0.0upgrade guideupgrade guide

  • Bleed moved from nextra-theme-docs to nextra/components for use in custom themes.

    4.0.0upgrade guide

  • Collapse moved from nextra-theme-docs to nextra/components for use in custom themes.

    4.0.0upgrade guide

  • collectCatchAllRoutes is removed.

    4.0.0upgrade guide

  • The color-primary-750 theme color variant is removed.

    4.0.0upgrade guide

  • compileMdx now returns Promise<string> instead of Promise<object>; use the returned string directly.

    4.0.0upgrade guideupgrade guide

  • contentDirBasePath replaces useContentDir to configure the content directory under a catch-all subdirectory.

    4.0.0upgrade guide

  • convertPageMapToJs is now synchronous.

    4.0.0upgrade guide

  • createCatchAllMeta is removed from nextra/catch-all.

    4.0.0upgrade guide

  • Details moved from nextra-theme-docs to nextra/components for use in custom themes.

    4.0.0upgrade guide

  • The editLink.component option is removed.

    4.0.0upgrade guide

  • editLink.content is replaced by the editLink option.

    4.0.0upgrade guide

  • The Search prop errorText replaces error.

    4.0.0upgrade guide

  • Generated MDX pages no longer contain export const title.

    4.0.0upgrade guide

  • External links declared in _meta files open in a new tab, include rel="noreferrer", and display a ↗ suffix icon.

    4.0.0upgrade guide

  • External Markdown links in MDX now open in a new tab, use rel="noreferrer", and display a ↗ suffix icon.

    4.0.0upgrade guide

  • The feedback.useLink option is removed.

    4.0.0upgrade guide

  • Folder gains a disabled prop when open is set, disabling click events and removing the pointer cursor.

    4.0.0upgrade guide

  • The footer prop is removed; the notes direct users to pass Footer as a child of Layout.

    4.0.0upgrade guide

  • getPageMap now accepts one optional root argument instead of lang and route arguments.

    4.0.0upgrade guide

  • gitTimestamp is replaced by lastUpdated.

    4.0.0upgrade guide

  • The theme.config head option is removed; configure dynamic head tags with the Next.js Metadata API or the Head component instead.

    4.0.0upgrade guide

  • Head moved from nextra-theme-docs to nextra/components for use in custom themes.

    4.0.0upgrade guide

  • The i18n.direction option is removed.

    4.0.0upgrade guide

  • lastUpdated replaces gitTimestamp as the option for last-updated behavior.

    4.0.0upgrade guide

  • Layout.banner is added as an optional prop.

    4.0.0upgrade guide

  • Layout.footer is a required prop, replacing the earlier direction to pass Footer as a child.

    4.0.0upgrade guide

  • Layout.navbar is a required prop, replacing the earlier direction to pass Navbar as a child.

    4.0.0upgrade guide

  • The mdx-components file replaces the providerImportSource option for component setup.

    4.0.0upgrade guide

  • MDXRemote replaces RemoteContent, is imported from nextra/mdx-remote, and receives default components automatically from mdx-components.jsx.

    4.0.0upgrade guideupgrade guide

  • _meta files must be server component files without a 'use client' directive; zod parses and transforms them on the server.

    4.0.0upgrade guide

  • Front matter fields are exported as an MDX metadata object; alternatively, export metadata directly, but do not use both in the same file.

    4.0.0upgrade guide

  • TypeScript projects should set moduleResolution to bundler instead of node to avoid type errors.

    4.0.0upgrade guide

  • The navbar prop is removed; the notes direct users to pass Navbar as a child of Layout.

    4.0.0upgrade guide

  • Navbar.logo no longer has a default value and is now required.

    4.0.0upgrade guide

  • The _meta newWindow field was removed.

    4.0.0upgrade guide

  • Nextra 4 requires Next.js 14 or later.

    4.0.0upgrade guideupgrade guide

  • Components formerly exported from the theme are now exported from nextra/components.

    3.0.0, 4.0.0release notesupgrade guide

  • Import the theme stylesheet directly; it was previously imported under the hood.

    4.0.0upgrade guideupgrade guide

  • Import the theme stylesheet in the application layout; it was previously imported under the hood.

    4.0.0upgrade guide

  • The nextraCofig.transform option is removed.

    4.0.0upgrade guide

  • The providerImportSource option is removed in favor of the mdx-components file.

    4.0.0upgrade guide

  • normalizePageRoute is removed.

    4.0.0upgrade guide

  • Search migrated from FlexSearch to Pagefind, with improved speed and support for indexing remote MDX, dynamic content, imported files, and static pages.

    4.0.0upgrade guideupgrade guiderelease notes

  • Install Pagefind as a dev dependency and run it after the build to index generated HTML pages.

    4.0.0upgrade guide

  • Pagefind output is moved to public/_pagefind.

    4.0.0upgrade guide

  • Remote docs setup now requires modifying the pageMap list in the layout file so sidebar navigation links display properly.

    4.0.0upgrade guide

  • Nextra 4 uses the Next.js App Router and discontinues support for the Pages Router.

    4.0.0upgrade guide

  • recmaRewriteFunctionBody is removed.

    4.0.0upgrade guide

  • recmaRewriteJsx is removed.

    4.0.0upgrade guide

  • renderComponent is removed.

    4.0.0upgrade guide

  • renderString is removed.

    4.0.0upgrade guide

  • The Search prop error is renamed to errorText.

    4.0.0upgrade guide

  • Select moved from nextra-theme-docs to nextra/components for use in custom themes.

    4.0.0upgrade guide

  • Sidebar titles now fall back to the first h1 Markdown heading after checking _meta, sidebarTitle, and title front matter.

    4.0.0upgrade guide

  • SkipNavContent moved from nextra-theme-docs to nextra/components for use in custom themes.

    4.0.0upgrade guide

  • SkipNavLink moved from nextra-theme-docs to nextra/components for use in custom themes.

    4.0.0upgrade guide

  • Summary moved from nextra-theme-docs to nextra/components for use in custom themes.

    4.0.0upgrade guide

  • Th, Tr, and Td are no longer standalone exports; use Table.Th, Table.Tr, and Table.Td instead.

    4.0.0upgrade guide

  • The standalone Td export is removed; use Table.Td instead.

    4.0.0upgrade guide

  • The standalone Th export is removed; use Table.Th instead.

    4.0.0upgrade guide

  • The theme option was removed from the nextra configuration.

    4.0.0upgrade guide

  • The theme.bottomContent field was removed.

    4.0.0upgrade guide

  • Nextra 4 no longer supports theme.config files for configuring theme options.

    4.0.0upgrade guide

  • The 'raw' layout option was removed; use page.{jsx,tsx} files to create pages without a layout.

    4.0.0upgrade guide

  • The theme.topContent field was removed.

    4.0.0upgrade guide

  • The themeConfig option was removed from the nextra configuration.

    4.0.0upgrade guide

  • The themeConfig prop is removed from Layout.

    4.0.0upgrade guide

  • themeSwitch.useOptions is refactored to the themeSwitch option.

    4.0.0upgrade guide

  • The standalone Tr export is removed; use Table.Tr instead.

    4.0.0upgrade guide

  • useContentDir is replaced by contentDirBasePath.

    4.0.0upgrade guide

  • Nextra’s useRouter hook was removed; use useRouter from next/navigation instead.

    4.0.0upgrade guide

  • Replace the useTOC export with a toc array export for supplying headings.

    4.0.0upgrade guide

  • The Tailwind CSS prefix for theme classes changed from _ to x:; update overridden theme classes accordingly.

    4.0.0upgrade guideupgrade guide

New APIs and options 23

  • Nextra 4 supports the App Router.

    4.0.0release notes

  • Set asIndexPage: true in front matter to use a page as the index for its folder.

    4.0.0upgrade guide

  • Set the path from which content is served when using the content directory convention.

    4.0.0upgrade guide

  • Use createIndexPage with getPageMap and MDXRemote to automatically render a route’s subpages as cards.

    4.0.0upgrade guide

  • Add this attribute to the tag enclosing the main content area of JavaScript or TypeScript pages that should be indexed.

    4.0.0upgrade guide

  • Add this attribute to tags whose content should be excluded from indexing.

    4.0.0upgrade guide

  • A getPageMap helper function is added to nextra/page-map.

    4.0.0upgrade guide

  • Markdown and MDX files can use GitHub alert syntax, which is rendered as Callout components.

    4.0.0upgrade guideupgrade guiderelease notes

  • The migration guide adds an app/layout.jsx root layout that composes the theme's Layout, Navbar, Footer, Banner, Head, and page map.

    4.0.0upgrade guide

  • Create a root mdx-components.jsx file to define global MDX components, using the theme's useMDXComponents as the base.

    4.0.0upgrade guide

  • mergeMetaWithPageMap is added to nextra/page-map.

    4.0.0upgrade guide

  • A single .global _meta file can define pages across folders; folder items must include an items field.

    4.0.0upgrade guiderelease notes

  • Configure content width using the CSS custom property --nextra-content-width.

    4.0.0upgrade guide

  • The page file convention supports MDX files using the enhanced App Router page extensions page.{md,mdx}.

    4.0.0upgrade guide

  • A Rust-powered Pagefind search engine provides faster performance and better search results.

    4.0.0upgrade guide

  • Translations can be dynamically loaded in server components and passed as props to theme components, avoiding client translation dictionary files.

    4.0.0upgrade guide

  • Built-in internationalization now supports React Server Components for multilingual websites.

    4.0.0upgrade guiderelease notes

  • Search is exported from nextra/components for use in custom themes.

    4.0.0upgrade guide

  • Nextra 4 supports Server/Client components.

    4.0.0release notes

  • A prefixed Tailwind CSS v4 layers stylesheet is exported for projects using Tailwind CSS v3.

    4.0.0upgrade guide

  • Add --turbopack to the Next.js dev command to use Turbopack.

    4.0.0upgrade guideupgrade guide

  • This option whitelists HTML elements to be replaced with components from mdx-components.js; by default, only details and summary are replaced.

    4.0.0upgrade guideupgrade guide

  • Wrap the Pre component with withIcons to provide custom icons for code block languages.

    4.0.0upgrade guide

Performance 3

  • Nextra 4 reports the smallest bundle size ever for a Nextra-powered website.

    4.0.0release notes

  • Imports from nextra/components, nextra-theme-docs, and nextra-theme-blog are optimized internally with Next.js optimizePackageImports to improve bundle size.

    4.0.0upgrade guide

  • Nextra components and hooks are optimized by React Compiler, and internal uses of useCallback, useMemo, and memo were removed.

    4.0.0upgrade guiderelease notes

Behavior and default changes 8

  • Diff code blocks with a filename now use the icon corresponding to that filename’s extension.

    4.0.0upgrade guide

  • JSX and TSX code blocks now display the React icon.

    4.0.0upgrade guide

  • The built-in page now includes an issue-creation URL containing the referrer URL, helping identify which broken page led to a 404.

    4.0.0upgrade guide

  • Page Map now collects static jsx and tsx pages from app/ in addition to static md and mdx pages.

    4.0.0upgrade guide

  • Pages and _meta files in app, plus content folder files, are added to pageMap; dynamic pages beginning [[ are ignored.

    4.0.0upgrade guide

  • Selection styles now use the primary color variant set through the color prop on <Head>.

    4.0.0upgrade guide

  • Projects can use src/content and src/app directories.

    4.0.0upgrade guide

  • Headings now animate when they are in the :target state.

    4.0.0upgrade guide

Tooling 1

Fixes and other changes 3

nextra-theme-docs 349 changes

Breaking changes 28

  • Renamed the theme option banner.text to banner.content.

    3.0.0release notes

  • Removed the image prop; an image is shown based on the truthiness of children instead.

    3.0.0release notes

  • Renamed the primaryHue theme option to color.hue.

    3.0.0release notes

  • Renamed the primarySaturation theme option to color.saturation.

    3.0.0release notes

  • Removed this configuration option.

    3.0.0release notes

  • Renamed the theme option editLink.text to editLink.content.

    3.0.0release notes

  • Removed the focus-visible polyfill.

    3.0.0release notes

  • Renamed the theme option footer.text to footer.content.

    3.0.0release notes

  • Added frontmatter support for setting a page label in the sidebar; this replaces frontmatter.sidebar_label.

    3.0.0release notes

  • Use the head option instead of next-seo and useNextSeoProps; its default is now null.

    3.0.0release notes

  • Renamed the theme option i18n.text to i18n.name.

    3.0.0release notes

  • Removed the intersection-observer polyfill.

    3.0.0release notes

  • Removed the MatchSorterSearch component.

    3.0.0release notes

  • Nextra now uses MDX3.

    3.0.0release notes

  • Support for _meta.json was removed; use _meta.{js,jsx,ts,tsx} instead.

    3.0.0release notes

  • useMDXComponents is now exported from nextra/mdx instead of the theme.

    3.0.0release notes

  • The removeLinks function moved from nextra-theme-docs to nextra/remove-links.

    3.0.0release notes

  • The Tailwind prefix changed from nx- to _ to reduce bundle size.

    3.0.0release notes

  • Removed PageOpts.toc; use the toc prop from components.wrapper.

    3.0.0release notes

  • The Next.js peer dependency requirement is now >=13.

    3.0.0release notes

  • React 18 is now the minimum requirement.

    3.0.0release notes

  • The project now uses shikiji instead of shiki.

    3.0.0release notes

  • Removed this option; use JSX to style separators and titles.

    3.0.0release notes

  • The className prop now uses render props exposing selected, disabled, and hover state.

    3.0.0release notes

  • The loading, placeholder, and themeSwitch.useOptions default theme options are now limited to English.

    3.0.0release notes

  • Renamed pageOpts.headings to toc.

    3.0.0release notes

  • Removed this option; use JSX to customize headings in the table of contents.

    3.0.0release notes

  • Renamed useSSG to useData.

    3.0.0release notes

New APIs and options 14

  • Added a Nextra configuration option to import official theme CSS into a specific cascade layer.

    3.0.0release notes

  • Added a dark-mode background color theme option.

    3.0.0release notes

  • Added a light-mode background color theme option.

    3.0.0release notes

  • Menu items now accept a Map, which guarantees insertion order.

    3.0.0release notes

  • Added MathJax support.

    3.0.0release notes

  • Added the useRouter hook entry point for accessing locale information.

    3.0.0release notes

  • Added the Playground component.

    3.0.0release notes

  • Added support for passing recmaPlugins in mdxOptions.

    3.0.0release notes

  • Added a theme option for bottom content.

    3.0.0release notes

  • Added a theme option for top content.

    3.0.0release notes

  • Exported the useMenu hook.

    3.0.0release notes

  • Added useRouter from nextra/hooks for fetching locale and defaultLocale.

    3.0.0release notes

  • Exported the useThemeConfig hook.

    3.0.0release notes

  • Code blocks can disable the mobile word-wrap button with the word-wrap=false metadata setting.

    3.0.0release notes

Performance 2

  • Search now loads flexsearch dynamically to reduce bundle size.

    3.0.0release notes

  • Mermaid is now loaded with a dynamic import.

    3.0.0release notes

Behavior and default changes 5

  • The docs theme backToTop option now supports i18n.

    3.0.0release notes

  • The icon prop is now optional.

    3.0.0release notes

  • Code blocks without a specified language now default to plaintext to preserve formatting.

    3.0.0release notes

  • The default value is now true.

    3.0.0release notes

  • The Tab component is crawlable and indexable by search engines by default.

    3.0.0release notes