nextra() Plugin Configuration Reference

The nextra() function is the default export of the nextra package and serves as the entry point for integrating Nextra into your Next.js project. It accepts a configuration object and returns a higher-order function that wraps your next.config — letting Nextra instrument the webpack and Turbopack pipelines, register MDX loaders, and inject the page-map build step transparently.

Function Signature

import nextra from 'nextra'

function nextra(config: NextraConfig): (nextConfig?: NextConfig) => NextConfig

Call nextra() once with your Nextra options to get withNextra, then pass your Next.js config object to that wrapper:

next.config.mjs

import nextra from 'nextra'

const withNextra = nextra({
  defaultShowCopyCode: true,
  search: { codeblocks: false },
  latex: true,
  mdxOptions: {
    rehypePlugins: [],
    remarkPlugins: [],
  },
})

export default withNextra({
  // Regular Next.js configuration here
})

The returned withNextra function merges Nextra’s webpack rules into your existing Next.js config rather than replacing it. All standard NextConfig options continue to work as expected.

NextraConfig Options

Core Options

defaultShowCopyCode

boolean

Enable the copy button for all code blocks by default, without needing to set the copy=true attribute in each code block’s metadata string. You can still disable the button on a per-block basis with copy=false.

boolean | { codeblocks: boolean }

default:"{ codeblocks: false }"

Enable search functionality powered by Pagefind. When enabled, Nextra adds the data-pagefind-body attribute to the <main> element so Pagefind can index your content.

Show search object options

search.codeblocks

boolean

required

Controls whether code blocks are included in the Pagefind index. When false, Nextra adds data-pagefind-ignore="all" to every <pre> element, so code is excluded from search results.

staticImage

boolean

default:"true"

Automatically optimise static image imports written with Markdown syntax (e.g. ![Alt text](/demo.png)). Nextra will pass these through Next.js <Image> for automatic resizing and format selection.

readingTime

boolean

Adds an estimated reading time to the front matter of every .md and .mdx file under the readingTime key. Powered by the reading-time package.

codeHighlight

boolean

default:"true"

Enable or disable syntax highlighting for code blocks. Highlighting is performed at build time by Rehype Pretty Code backed by Shiki. Disable this if you want to use a different client-side highlighter.

Allows additional HTML elements to be replaced by components defined in mdx-components.js. By default Nextra only replaces <details> and <summary>. Pass extra tag names here to extend that behaviour.

contentDirBasePath

string

default:"/"

Serve your .md and .mdx files from the content directory at a custom URL path instead of the root (/). Must begin with / and must not end with / (except for the root itself).

// Files in content/ will be served under /docs/...
nextra({ contentDirBasePath: '/docs' })

unstable_shouldAddLocaleToLinks

boolean

default:"false"

Prefixes the current locale to all links in the page-map. Useful for i18n setups where you manage routing yourself and don’t want to use Nextra’s built-in middleware.

This option is unstable and its API may change in a future minor release.

mdxOptions

MdxOptions

default:"{}"

Fine-grained control over the MDX compilation pipeline. All sub-options are optional.

Show mdxOptions fields

mdxOptions.remarkPlugins

ProcessorOptions['remarkPlugins']

Additional remark plugins applied during Markdown parsing. Plugins run after Nextra’s built-in set (GFM, front matter, headings, etc.).

mdxOptions.rehypePlugins

ProcessorOptions['rehypePlugins']

Additional rehype plugins applied during HTML transformation. Plugins run before Nextra’s built-in set (Pretty Code, KaTeX, etc.).

mdxOptions.recmaPlugins

ProcessorOptions['recmaPlugins']

Additional recma plugins that operate on the JavaScript AST after MDX compilation. This ecosystem is currently in beta.

mdxOptions.format

'detect' | 'mdx' | 'md'

default:"'detect'"

How Nextra should interpret source files:

'detect' — infer from file extension (.mdx → MDX, .md → Markdown)
'mdx' — always treat as MDX
'md' — always treat as plain Markdown

mdxOptions.rehypePrettyCodeOptions

RehypePrettyCodeOptions

default:"{}"

Options forwarded directly to Rehype Pretty Code. Use this to customise the Shiki theme, add language aliases, or configure transformers. See the Rehype Pretty Code docs for all available fields.

latex

boolean | KatexConfig | MathjaxConfig

Enable LaTeX math rendering. Pass true to use KaTeX with default settings, or supply a renderer-specific object for fine-grained control.

Show KaTeX config object

latex.renderer

'katex'

required

Select KaTeX as the renderer. KaTeX pre-renders math at build time to static HTML — no client-side JavaScript required.

latex.options

RehypeKatexOptions

Options forwarded to rehype-katex. See the KaTeX options reference for all available fields.

Show MathJax config object

latex.renderer

'mathjax'

required

Select MathJax as the renderer. MathJax renders math dynamically in the browser, which supports a broader range of LaTeX commands at the cost of a small runtime bundle.

latex.options

MathJaxOptions

Show MathJaxOptions fields

latex.options.src

string

default:"\"https://cdnjs.cloudflare.com\""

CDN URL for the MathJax script.

latex.options.config

MathJax3Config

MathJax 3 configuration object. See the MathJax docs for all available fields.

Full Configuration Example

import nextra from 'nextra'

const withNextra = nextra({
  defaultShowCopyCode: true,
  search: { codeblocks: false },
  latex: {
    renderer: 'katex',
    options: { strict: false },
  },
  mdxOptions: {
    remarkPlugins: [],
    rehypePlugins: [],
    rehypePrettyCodeOptions: {
      theme: 'github-dark',
    },
  },
  contentDirBasePath: '/docs',
})

export default withNextra({
  reactStrictMode: true,
})

You can run next dev --turbopack with Nextra. Turbopack support is configured automatically — no extra flags needed in nextra().

Core API

Docs Theme API

Blog Theme API

nextra() Plugin Configuration Reference

Function Signature

NextraConfig Options

Core Options

mdxOptions

latex

Full Configuration Example

Build docs developers (and LLMs) love

Core API

Docs Theme API

Blog Theme API

Documentation Index

​Function Signature

​NextraConfig Options

​Core Options

​mdxOptions

​latex

​Full Configuration Example

Build docs developers (and LLMs) love

Function Signature

NextraConfig Options

Core Options

mdxOptions

latex

Full Configuration Example