Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shuding/nextra/llms.txt

Use this file to discover all available pages before exploring further.

Nextra supports mathematical typesetting through two renderers: KaTeX pre-renders LaTeX expressions at build time for fast, flicker-free display, while MathJax renders math dynamically in the browser with richer accessibility features. LaTeX support is disabled by default and must be enabled in your Nextra configuration.

​
Setup

1
Enable the latex option
2
Set latex: true in your next.config.mjs to enable KaTeX rendering (the default renderer):
3
import nextra from 'nextra'

const withNextra = nextra({
  latex: true
})

export default withNextra({})
4
To explicitly choose a renderer, pass an object instead of true:
5
KaTeX (default)
import nextra from 'nextra'

const withNextra = nextra({
  latex: {
    renderer: 'katex'
  }
})

export default withNextra({})
MathJax
import nextra from 'nextra'

const withNextra = nextra({
  latex: {
    renderer: 'mathjax'
  }
})

export default withNextra({})
6
Apply KaTeX styles (KaTeX only)
7
KaTeX requires its CSS to render correctly. Choose one of the following methods:
8
Import from katex package
Install the katex package and import its stylesheet in your root layout:
npm i katex

import 'katex/dist/katex.min.css'
Load from CDN
Add a <link> tag directly in your root layout file. Note that <link rel="stylesheet" /> is not supported via the Next.js Metadata API, so include it as JSX:
export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <link
          rel="stylesheet"
          href="https://cdn.jsdelivr.net/npm/katex/dist/katex.css"
        />
      </head>
      <body>{children}</body>
    </html>
  )
}
Alternatively, include the <link> directly in any individual MDX file where KaTeX is used.
9
MathJax does not require a separate CSS install — it is served via the MathJax CDN by default and includes all necessary styling.

​
Writing Math

Once enabled, you can write LaTeX expressions in your MDX files.

​
Inline Math

Wrap an expression in single dollar signs for inline math: 
The **Pythagorean equation** is $a = \sqrt{b^2 + c^2}$.
Renders as: The Pythagorean equation is a=b2+c2a = \sqrt{b^2 + c^2}.

​
Block Math

Use a fenced code block with the math language tag for display (block-level) equations: 
```math
\int_0^\infty e^{-x^2} \, dx = \frac{\sqrt{\pi}}{2}
```

​
Full Example

The **Pythagorean equation** is $a=\sqrt{b^2 + c^2}$ and the quadratic formula:

```math
x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}


<Tip>
  To display a literal `$` sign in your content without triggering math
  rendering, escape it with a backslash: `\$e = mc^2\$` renders as
  \$e = mc^2\$.
</Tip>

## API Reference

### KaTeX Options

`rehype-katex` is used under the hood. Pass [KaTeX options](https://katex.org/docs/options) via the `options` key:

```js filename="next.config.mjs"
const withNextra = nextra({
  latex: {
    renderer: 'katex',
    options: {
      macros: {
        '\\RR': '\\mathbb{R}'
      }
    }
  }
})
See KaTeX’s supported commands for the full list of available LaTeX features.

​
MathJax Options

When using MathJax, math is rendered client-side via better-react-mathjax. Pass configuration through the options key: 
const withNextra = nextra({
  latex: {
    renderer: 'mathjax',
    options: {
      config: {
        tex: {
          macros: {
            RR: '\\mathbb{R}'
          }
        }
      }
    }
  }
})
OptionTypeDescription
options.srcstringURL for the MathJax script. Defaults to the MathJax CDN at cdnjs.cloudflare.com.
options.configobjectMathJax configuration passed at init time.
Only serializable values can be passed via options in next.config.mjs. To pass Functions or other non-serializable objects, use the <MathJaxContext config={...} /> component directly in your MDX source.

​
KaTeX vs. MathJax

KaTeX

Pre-renders math at build time — no flicker, fastest possible page loads. Does not support all LaTeX features, particularly those related to accessibility.

MathJax

Renders math at page load in the browser. Tab-accessible formulas with a context menu that helps screen readers reprocess math for the visually impaired. Supports a broader set of LaTeX features.

​
Configuration Reference

OptionTypeDefaultDescription
latexboolean | { renderer: 'katex' | 'mathjax', options?: {...} }undefinedEnable LaTeX support and choose a renderer.
latex.renderer'katex' | 'mathjax''katex'Which math renderer to use.
latex.optionsRehypeKatexOptions | MathJaxOptions{}Renderer-specific options.

Build docs developers (and LLMs) love

Get started for freeTalk to us