# What changed in nextra-theme-docs

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

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

## nextra-theme-docs 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), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Bleed 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)
- Collapse 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)
- collectCatchAllRoutes is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/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-theme-docs/CHANGELOG.md)
- compileMdx now returns Promise<string> instead of Promise<object>; use the returned string directly. (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-theme-docs/CHANGELOG.md)
- contentDirBasePath replaces useContentDir to configure the content directory under a catch-all subdirectory. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- convertPageMapToJs is now synchronous. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- createCatchAllMeta is removed from nextra/catch-all. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Details 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)
- The editLink.component option is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- editLink.content is replaced by the editLink option. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The Search prop errorText replaces error. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Generated MDX pages no longer contain export const title. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- External links declared in _meta files open in a new tab, include 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)
- External Markdown links in MDX now 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)
- The feedback.useLink option is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Folder gains a disabled prop when open is set, disabling click events and removing the pointer cursor. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The footer prop is removed; the notes direct users to pass Footer as a child of Layout. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- 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-theme-docs/CHANGELOG.md)
- gitTimestamp is replaced by lastUpdated. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The theme.config head option is removed; configure dynamic head tags with the Next.js Metadata API or the Head component 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)
- 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)
- The i18n.direction option is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- lastUpdated replaces gitTimestamp as the option for last-updated behavior. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Layout.banner is added as an optional prop. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Layout.footer is a required prop, replacing the earlier direction to pass Footer as a child. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Layout.navbar is a required prop, replacing the earlier direction to pass Navbar as a child. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The mdx-components file replaces the providerImportSource option for component setup. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- MDXRemote replaces RemoteContent, is imported from nextra/mdx-remote, and receives default components 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), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- _meta files must be server component files 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)
- 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.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 navbar prop is removed; the notes direct users to pass Navbar as a child of Layout. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Navbar.logo no longer has a default value and is now required. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- 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)
- 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-theme-docs/CHANGELOG.md)
- Components formerly exported from the theme are now exported from `nextra/components`. (3.0.0, 4.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Import the theme stylesheet directly; it was previously imported under the hood. (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-theme-docs/CHANGELOG.md)
- Import the theme stylesheet in the application layout; it was previously imported under the hood. (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 nextraCofig.transform option is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The providerImportSource option is removed in favor of the mdx-components file. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- normalizePageRoute is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Search migrated from FlexSearch to Pagefind, with improved speed and support for indexing remote MDX, dynamic 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-theme-docs/CHANGELOG.md), [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%404.0.0)
- Install Pagefind as a dev dependency and run it after the build 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)
- Pagefind output is moved to public/_pagefind. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Remote docs setup now requires modifying the pageMap list in the layout file so sidebar navigation links display properly. (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 the Next.js App Router and discontinues support for the Pages Router. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- recmaRewriteFunctionBody is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- recmaRewriteJsx is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- renderComponent is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- renderString is removed. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The Search prop error is renamed to errorText. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Select 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)
- Sidebar titles now fall back to the first h1 Markdown 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)
- SkipNavContent 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)
- SkipNavLink 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)
- Summary 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)
- Th, Tr, and Td are no longer standalone exports; use Table.Th, Table.Tr, and Table.Td 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 standalone Td export is removed; use Table.Td instead. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The standalone Th export is removed; use Table.Th instead. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The theme option was removed from the 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 'raw' layout 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 the 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 themeConfig prop is removed from Layout. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- themeSwitch.useOptions is refactored to the themeSwitch option. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The standalone Tr export is removed; use Table.Tr instead. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- useContentDir is replaced by contentDirBasePath. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/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)
- Replace the useTOC export with a toc array export for supplying headings. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The Tailwind CSS prefix for theme classes 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-theme-docs/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-theme-docs%404.0.0)
- Set asIndexPage: true in front matter to use a page 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)
- Use createIndexPage with getPageMap and MDXRemote to automatically render a route’s subpages as cards. (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 the tag enclosing the main content area of JavaScript or TypeScript pages that should be indexed. (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 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)
- A getPageMap helper function is added to nextra/page-map. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Markdown and MDX files can use GitHub alert syntax, which is rendered 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), [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md), [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%404.0.0)
- 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.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Create a root mdx-components.jsx file to define global MDX components, using the theme's useMDXComponents as the base. (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-theme-docs/CHANGELOG.md)
- A single .global _meta file can define pages across folders; 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), [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%404.0.0)
- Configure content width using the CSS custom property --nextra-content-width. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- The page file convention supports MDX files using the enhanced App Router page extensions page.{md,mdx}. (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 Pagefind 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)
- Translations can be dynamically loaded in server components and passed as props to theme components, avoiding 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)
- Built-in internationalization now supports React Server Components for multilingual websites. (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-theme-docs%404.0.0)
- Search is exported from 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)
- Nextra 4 supports Server/Client components. (4.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%404.0.0)
- A prefixed Tailwind CSS v4 layers stylesheet is exported for projects using Tailwind CSS v3. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Add --turbopack to the Next.js dev command to use 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-theme-docs/CHANGELOG.md)
- This option whitelists 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-theme-docs/CHANGELOG.md)
- Wrap the Pre component with withIcons to provide custom icons for code block 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)

### Performance

- Nextra 4 reports the smallest bundle size ever for a Nextra-powered website. (4.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%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)
- Nextra components and hooks are optimized by React Compiler, and internal uses of useCallback, useMemo, and memo were 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), [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%404.0.0)

### Behavior and default changes

- Diff code blocks with a filename now use the icon corresponding to that filename’s 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)
- JSX and TSX code blocks now display the React 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)
- 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.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Page Map now collects static jsx and tsx pages from app/ in addition to 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)
- Pages and _meta files in app, plus content folder files, are added to pageMap; dynamic pages beginning [[ are ignored. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Selection styles now use the primary color variant set through the color prop on <Head>. (4.0.0) — [upgrade guide](https://the-guild.dev/blog/nextra-4?utm_source=github.com&utm_campaign=releases_page&utm_content=release_link)
- Projects can use src/content and src/app directories. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Headings now animate when they are 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 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-theme-docs%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-theme-docs%404.6.1)
- Projects can use src/app and src/content directories. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)
- Steps now supports h5 and h6 tags. (4.0.0) — [upgrade guide](https://github.com/shuding/nextra/blob/main/packages/nextra-theme-docs/CHANGELOG.md)

## nextra-theme-docs 3

### Breaking changes

- Renamed the theme option `banner.text` to `banner.content`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Removed the `image` prop; an image is shown based on the truthiness of `children` instead. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Renamed the `primaryHue` theme option to `color.hue`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Renamed the `primarySaturation` theme option to `color.saturation`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Removed this configuration option. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Renamed the theme option `editLink.text` to `editLink.content`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Removed the focus-visible polyfill. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Renamed the theme option `footer.text` to `footer.content`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Added frontmatter support for setting a page label in the sidebar; this replaces `frontmatter.sidebar_label`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Use the `head` option instead of `next-seo` and `useNextSeoProps`; its default is now `null`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Renamed the theme option `i18n.text` to `i18n.name`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Removed the intersection-observer polyfill. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Removed the `MatchSorterSearch` component. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Nextra now uses MDX3. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Support for `_meta.json` was removed; use `_meta.{js,jsx,ts,tsx}` instead. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- `useMDXComponents` is now exported from `nextra/mdx` instead of the theme. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- The `removeLinks` function moved from `nextra-theme-docs` to `nextra/remove-links`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- The Tailwind prefix changed from `nx-` to `_` to reduce bundle size. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Removed `PageOpts.toc`; use the `toc` prop from `components.wrapper`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- The Next.js peer dependency requirement is now `>=13`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- React 18 is now the minimum requirement. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- The project now uses `shikiji` instead of `shiki`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Removed this option; use JSX to style separators and titles. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- The `className` prop now uses render props exposing `selected`, `disabled`, and `hover` state. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- The `loading`, `placeholder`, and `themeSwitch.useOptions` default theme options are now limited to English. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Renamed `pageOpts.headings` to `toc`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Removed this option; use JSX to customize headings in the table of contents. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Renamed `useSSG` to `useData`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)

### New APIs and options

- Added 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-theme-docs%403.0.0)
- Added a dark-mode background color theme option. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Added a light-mode background color theme option. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Menu items now accept a `Map`, which guarantees insertion order. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Added MathJax support. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Added the `useRouter` hook entry point for accessing locale information. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Added the `Playground` component. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Added support for passing `recmaPlugins` in `mdxOptions`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Added a theme option for bottom content. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Added a theme option for top content. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Exported the `useMenu` hook. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Added `useRouter` from `nextra/hooks` for fetching `locale` and `defaultLocale`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Exported the `useThemeConfig` hook. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Code blocks can disable the mobile word-wrap button with the `word-wrap=false` metadata setting. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)

### Performance

- Search now loads `flexsearch` dynamically to reduce bundle size. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Mermaid is now loaded with a dynamic import. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)

### Behavior and default changes

- The docs theme `backToTop` option now supports i18n. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- The `icon` prop is now optional. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- Code blocks without a specified language now default to plaintext to preserve formatting. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%403.0.0)
- The default value is now `true`. (3.0.0) — [release notes](https://github.com/shuding/nextra/releases/tag/nextra-theme-docs%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-theme-docs%403.0.0)