# What changed in nextra

> 156 changes in nextra 3 to 4 from its official release notes, upgrade guides and advisories: 101 breaking, 37 new APIs and options. Each one cited. Sources checked 2026-10-23. HTML: https://unstale.sh/npm/nextra/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## nextra 4

### Breaking changes

- Nextra 4 exclusively uses the Next.js App Router; Pages Router support has been discontinued. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Nextra 4 uses Next.js App Router and discontinues Pages Router support. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- collectCatchAllRoutes is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The color-primary-750 theme color variant is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- compileMdx now returns Promise<string> instead of Promise<object>. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- contentDirBasePath replaces useContentDir and configures the content directory under a catch-all subdirectory. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- convertPageMapToJs is now synchronous. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- createCatchAllMeta is removed from nextra/catch-all. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Use `display: 'hidden'` in a blog `_meta` file instead of the `draft: true` front matter option. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- External links in MDX now open in a new tab with rel="noreferrer" and a visual ↗ suffix icon. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- getPageMap now accepts one optional root argument instead of lang and route arguments. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The Head component moves to nextra/components. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- mdx-components replaces nextraConfig.mdxOptions.providerImportSource for adding or overriding code-block icons. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The server component is named `<MDXRemote>`; it was previously called `<RemoteContent>`. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Use MDXRemote from nextra/mdx-remote; its default components are provided automatically from mdx-components.jsx. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- These files must be server components without a `'use client'` directive; zod parses and transforms them on the server. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- External links declared in `_meta` files open in a new tab, use `rel="noreferrer"`, and display a `↗` suffix icon. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Front matter fields are exported as an MDX `metadata` object; MDX files may instead export `metadata` directly, but cannot use both approaches. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- TypeScript projects should set moduleResolution to bundler instead of node to avoid type errors. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `_meta` `newWindow` field was removed. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Use the Next.js Metadata API instead of the `head` theme config option for dynamic head tags. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Nextra 4 requires Next.js 14 or later. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Several components, including `<Collapse>`, `<Details>`, `<Summary>`, `<Select>`, and `<Head>`, moved from `nextra-theme-docs` to `nextra/components` for use in custom themes. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Components including Collapse, Details, Summary, SkipNavContent, SkipNavLink, Select, and Bleed move from nextra-theme-docs to nextra/components. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The nextra/context entry point is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The nextra/mdx entry point is renamed to nextra/mdx-components. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The nextra/remark-plugins entry point is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The nextra/remote entry point is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The nextra/schemas entry point is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- NextraConfig.transformPageMap is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The NextraThemeLayoutProps type is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- normalizePageRoute is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Search migrated from FlexSearch to Pagefind, which indexes remote MDX, dynamic Markdown/MDX content, imported files, and static pages. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md), [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.0.0)
- Install Pagefind as a dev dependency and run it after building to index generated HTML pages. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Remote docs setups need a modified pageMap list in the layout file for sidebar navigation links to display correctly. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The optional peer dependency was removed; the theme uses the Cusdis SDK directly in its `<Comments>` component. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- RemoteContent was renamed to MDXRemote and moved from nextra/components to nextra/mdx-remote. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- renderComponent is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- renderString is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Sidebar titles now fall back to the first Markdown h1 heading after checking _meta, sidebarTitle, and title front matter. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Theme stylesheets are no longer imported by themes; import the appropriate theme style.css manually. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Th, Tr, and Td are now accessed as Table.Th, Table.Tr, and Table.Td instead of separate imports. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The standalone Td export was removed; use Table.Td. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The standalone Th export was removed; use Table.Th. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The `theme` option was removed from Nextra configuration. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `theme.bottomContent` field was removed. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Nextra 4 no longer supports theme.config files for configuring theme options. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `components` theme config option was removed; provide custom components inside `useMDXComponents` instead. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `direction` theme config option was removed; set the `dir` attribute on the `<html>` tag. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `feedback.useLink` theme config option was removed. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `head` theme config option was removed; use `<Head>` or the Next.js Metadata API. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `main` theme config option was removed. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `themeSwitch.component` theme config option was removed. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `toc.component` theme config option was removed. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `theme.layout: 'raw'` option was removed; use `page.{jsx,tsx}` files to create pages without a layout. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `theme.topContent` field was removed. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The `themeConfig` option was removed from Nextra configuration. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Generated MDX pages no longer export const title. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The exported TOC value is now toc instead of useTOC. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The standalone Tr export was removed; use Table.Tr. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Nextra’s useRouter hook was removed; use useRouter from next/navigation instead. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The theme’s Tailwind CSS class prefix changed from `_` to `x:`; update overridden theme classes accordingly. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)

### New APIs and options

- Nextra 4 supports the App Router. (4.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.0.0)
- Set asIndexPage: true in front matter to make a page serve as the index for its folder. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Set the path from which content is served when using the Content Directory Convention. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Create a rendered listing of a route’s subpages, using getPageMap to supply the page map. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Mark the main content area of JavaScript or TypeScript pages to have its content indexed by Pagefind. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Add this attribute to tags whose content should be excluded from Pagefind indexing. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Get a route’s page map for use with createIndexPage to list its subpages. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The docs and blog themes support rendering GitHub alert syntax in Markdown and MDX as Callout components. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.0.0)
- Set the optional icon front matter field on a subpage to show an icon on its card. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Add an app layout file to configure the Nextra layout, theme components, metadata, and page map. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Create this root-level file to define global MDX components. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- mergeMetaWithPageMap is added to nextra/page-map. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Define pages across folders in one suffixed `_meta` file; folder items must include an `items` field. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- A root _meta.global file is added; supported extensions include js, jsx, ts, and tsx. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Nextra 4 introduces the _meta.global file. (4.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.0.0)
- Add `--turbopack` to the dev command to use Nextra with Turbopack. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The blog theme adds support for the View Transitions API using this package. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- normalizePagesResult gains activeMetadata to retrieve front matter or metadata exported from a page. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- The Page File Convention uses the Next.js App Router convention with enhanced page extensions for MD and MDX files. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- A Rust-powered search engine provides faster performance and better search results. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The Search component is exported from `nextra/components` for use in custom themes; the blog theme also supports search. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The blog theme supports built-in search; import `<Search>` from `nextra/components` and place it inside `<Navbar>`. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Nextra 4 adds support for Server/Client components. (4.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.0.0)
- Translations can be dynamically loaded in server components and passed as props to theme components, avoiding shipping client translation dictionary files. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Whitelist HTML elements to be replaced with components from `mdx-components.js`; by default only `<details>` and `<summary>` are replaced. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)
- Wrap the Pre component with custom icons for specified code languages. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Wrapper gains a bottomContent prop for placing content after pagination in nextra-theme-docs. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra/CHANGELOG.md)

### Performance

- The Docs Example's shared First Load JS decreased by 36.9%, from 168 kB to 106 kB. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.0.0)
- Imports from nextra/components, nextra-theme-docs, and nextra-theme-blog are optimized internally with Next.js optimizePackageImports to improve bundle size. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)

### Behavior and default changes

- JSX and TSX code blocks now display the React icon; diff blocks with a filename use the icon for that file extension. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The built-in 404 page includes an issue-creation URL with the referrer URL to help identify broken links. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Page collection now includes static jsx and tsx pages from the app directory, as well as static md and mdx pages. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Built-in internationalization capabilities now support React Server Components. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.0.0)
- The primary color variant set through the Head component’s color prop is now used for text selection styles. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- The table of contents can show React components, interpolated variables, and LaTeX, including for remote content. (3.0.0, 4.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0), [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Headings now animate when in the `:target` state. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)

### Tooling

- Nextra 4 is compiled by React-Compiler. (4.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.0.0)
- Nextra 4 adds Turbopack support for an improved development experience. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link), [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.0.0)

### Fixes and other changes

- Fixes compatibility with Next.js 16. (4.6.1) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%404.6.1)

## nextra 3

### Breaking changes

- The `_app.mdx` convention is removed; use `_app.{js,jsx}` or `_app.{ts,tsx}` for TypeScript projects instead. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The standalone `Card` export is removed; use `Cards.Card` instead. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `image` prop is removed; image display is determined by the truthiness of `children`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The minimum supported Node.js version is 18. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Nextra bundles to ESM only; use `next.config.mjs` or `next.config.js` with `type: module`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Support for `frontMatter.mdxOptions` is removed. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `layout.tsx` is removed; move directly to `setup-page.tsx`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `defaultLocale` is removed from `LoaderOptions`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Importing MD or MDX files outside the working directory is disallowed; use symlinks instead. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Nextra updates to MDX3. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Support for `_meta.json` is removed; use `_meta.{js,jsx,ts,tsx}` instead. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The package declares `type: module` and is bundled to ESM only; use `next.config.mjs` or `next.config.js` with `type: module`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `nextra/filter-route-locale` export is removed. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The route-specific `themeConfig` internal context field is removed. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The Nextra middleware export is removed. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `nextra/mdx-plugins` export is removed; `nextra/remark-plugins` is added. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `resolvePageMap` moves to `nextra/page-map-dynamic`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Adds the `nextra/remove-links` export. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `nextraConfig.flexsearch` option is renamed to `nextraConfig.search`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `hot` page option is removed. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `pageNextRoute` page option is removed. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `pageOptsChecksum` page option is removed. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `locale` and `defaultLocale` are removed from `normalizePages`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The Tailwind prefix changes from `nx-` to `_` to reduce bundle size. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `pageMapCache` is removed from `nextra/page-map`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `pageOpts.headings` is renamed to `toc`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `pageOpts.newNextLinkBehavior` field is removed. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `pageOpts.route` field is removed. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Remove `PageOpts.toc`; use the `toc` prop from `components.wrapper`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `parseFileName` is removed from `nextra/utils`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The Next.js peer dependency requirement is set to `>=13`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- React 18 becomes the minimum requirement. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `RemoteContent` moves from `nextra/data` to `nextra/components`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `resolvePageMap` is removed from `nextra/page-map`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Nextra switches to `shikiji` instead of `shiki` for syntax highlighting. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The standalone `Tab` export is removed; use `Tabs.Tab` instead. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The Nextra option `transformPageOpts` is replaced by `transformPageMap`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `useData` moves from `nextra/data` to `nextra/hooks`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `useSSG` is renamed to `useData`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)

### New APIs and options

- Adds a Nextra configuration option to import official theme CSS into a specific cascade layer. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Front matter can set the page label shown in the sidebar. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Adds MathJax support. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Adds support for JavaScript and TypeScript `_meta` files, including JSX. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Adds the `nextra/fetch-filepaths-from-github` export. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Adds `useRouter` for fetching `locale` and `defaultLocale`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `recmaPlugins` can be passed in `mdxOptions`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Adds `remark-smartypants` support. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Adds shikiji twoslash support. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Code block metadata can set `word-wrap=false` to disallow the mobile word-wrap button. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)

### Behavior and default changes

- The `icon` prop becomes optional. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Front matter is inserted as an export node via a custom remark plugin. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Nextra configuration gains Zod validation. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- Repeated imports of the same image are deduplicated, and images can be imported through Markdown image definitions. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- `className` uses render props with `selected`, `disabled`, and `hover` state. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)
- The `Tab` component is crawlable and indexable by search engines by default. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra%403.0.0)