rehype-katex Setup: remark-math, KaTeX CSS and Fixes
November 11, 2026 · 9 min read
rehype-katex: Render Math in Markdown with remark-math
rehype-katex is a unified plugin that turns math in Markdown into KaTeX HTML when the Markdown is compiled. You pair it with remark-math, which parses $...$ and $$...$$, then load KaTeX's stylesheet so the output looks right. This tutorial wires it into unified, react-markdown and MDX, and fixes the errors people hit most.
What remark-math and rehype-katex Each Do
The two plugins split the job in half. remark-math is a syntax extension: it teaches the Markdown parser that dollar signs mark math. It doesn't render anything. When the Markdown tree becomes an HTML tree, each math node turns into a plain code element with a class name.
Inline math becomes <code class="language-math math-inline">. Block math becomes <pre><code class="language-math math-display">. The rendering plugin then finds every element with one of those classes and swaps in the markup KaTeX produces.
That happens at compile time, so a prebuilt page needs no client-side JavaScript to show the equations. If you run react-markdown in the browser, KaTeX runs there instead. The split also sets the plugin order: remark-math belongs with the remark plugins, and rehype-katex runs later with the rehype plugins.
If you'd rather render with MathJax, rehype-mathjax is the drop-in alternative. Its readme says MathJax output needs no extra CSS. KaTeX output does, and that's the step most broken setups skip.
The KaTeX plugin also renders fenced code with a math info string, so this works even without remark-math's dollar syntax:
```math
L = \frac{1}{2} \rho v^2 S C_L
```
That fence renders as a centered display equation, exactly like a $$ block.
Install remark-math, rehype-katex and KaTeX
Install the two plugins plus KaTeX itself. KaTeX goes in as a direct dependency so you can import its stylesheet. Pin it to 0.16 for now; the next sections explain why.
npm install remark-math rehype-katex katex@0.16
As of November 2026, npm lists remark-math 6.0.0 and rehype-katex 7.0.1. Both packages are ESM only and support Node.js 16 and later, per their readmes. You import them with import, not require().
Wire rehype-katex Into a unified Pipeline
Here's the plain unified version, which every other setup builds on. remark-parse reads Markdown, remark-math adds math syntax, remark-rehype converts to HTML, rehype-katex renders the math, and rehype-stringify prints the result.
import rehypeKatex from 'rehype-katex'
import rehypeStringify from 'rehype-stringify'
import remarkMath from 'remark-math'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'
const file = await unified()
.use(remarkParse)
.use(remarkMath)
.use(remarkRehype)
.use(rehypeKatex)
.use(rehypeStringify)
.process('Energy: $E = mc^2$')
console.log(String(file))
The output is a paragraph containing a <span class="katex"> element. Inside it sit two copies of the equation: a MathML version for screen readers and an HTML version (katex-html) for display. Drop the KaTeX step from the chain and you'd see the raw <code class="language-math math-inline">E = mc^2</code> instead. That's a handy way to check that remark-math is parsing your input.
rehype-katex takes KaTeX's own options, except displayMode and throwOnError, which the plugin sets itself. Custom macros are the most useful one, because they let you write a shorthand once for every page:
.use(rehypeKatex, {macros: {'\\RR': '\\mathbb{R}'}})
With that in place, $x \in \RR$ renders as x ∈ ℝ, with the blackboard-bold R that \mathbb produces.
If you also use a syntax highlighter such as rehype-highlight, put rehype-katex before it. The math plugin replaces the language-math code blocks, so the highlighter never sees them.
How Do You Use rehype-katex with react-markdown?
react-markdown accepts the same plugins through two props. remark-math goes in remarkPlugins, rehype-katex goes in rehypePlugins, and you import the CSS yourself:
import Markdown from 'react-markdown'
import rehypeKatex from 'rehype-katex'
import remarkMath from 'remark-math'
import 'katex/dist/katex.min.css'
export function Article({source}) {
return (
<Markdown remarkPlugins={[remarkMath]} rehypePlugins={[rehypeKatex]}>
{source}
</Markdown>
)
}
The react-markdown readme spells out the catch in a code comment: the plugin does not import the CSS for you. For installing react-markdown, rendering custom components and sanitizing input, see our react-markdown guide.
Add Math to MDX and Next.js
MDX takes the same two arrays. With @mdx-js/mdx, pass them to compile:
import {compile} from '@mdx-js/mdx'
import rehypeKatex from 'rehype-katex'
import remarkMath from 'remark-math'
const code = await compile(source, {
remarkPlugins: [remarkMath],
rehypePlugins: [rehypeKatex]
})
In Next.js with @next/mdx, the options go to createMDX. Turbopack needs one change: plugins are named as strings, because JavaScript functions can't be passed to its Rust side. The Next.js MDX guide also notes that plugins with non-serializable options don't work under Turbopack yet.
import createMDX from '@next/mdx'
const withMDX = createMDX({
options: {
remarkPlugins: ['remark-math'],
rehypePlugins: ['rehype-katex']
}
})
export default withMDX({
pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx']
})
Import katex/dist/katex.min.css once in your root layout. Docusaurus wires the same pair through its own config file, which our Docusaurus Markdown guide covers.
Load katex.min.css That Matches Your KaTeX Version
Without KaTeX's stylesheet, the output shows each equation twice or as jumbled plain text, because nothing hides the MathML copy or positions the HTML copy. The stylesheet also loads KaTeX's fonts.
The version trap is easy to miss. rehype-katex 7.0.1 depends on katex@^0.16.0, while the newest KaTeX on npm is 0.19.1 as of November 2026. Run a bare npm install katex and npm puts 0.19.1 at the top level, while the plugin keeps its own nested 0.16 copy. Your import 'katex/dist/katex.min.css' then loads the 0.19 stylesheet for 0.16 markup, and the two stylesheets aren't guaranteed to match.
Installing katex@0.16, as shown earlier, lets npm share one copy. Check with:
npm ls katex
Every line should show the same version. We prefer importing the CSS from node_modules over pasting a CDN link, because the stylesheet then updates whenever the package does. If you do use a CDN tag, pin it to the exact version npm ls reports.
One caveat as of November 2026: a low-severity KaTeX advisory (GHSA-238p-pmpm-9mq7, about prototype pollution and the trust option) is fixed in katex 0.18.2. That's outside rehype-katex 7.0.1's range, and remark-math issue #121 asks to allow newer KaTeX. Watch that issue before you upgrade.
Inline vs Display Math and the singleDollarTextMath Option
remark-math follows the micromark math syntax. Single dollars make inline math, and $$ on lines of their own makes a display block:
Mass-energy: $E = mc^2$ sits inside the sentence.
$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$
This is still inline: $$a^2 + b^2$$ in the middle of a line.
The first and third equations render inline. Only the middle one becomes a centered block, because block math needs the opening and closing $$ on separate lines. Writing $$x$$ on one line produces inline math, even when it's alone in its paragraph.
Single dollars cause trouble in prose about money. With the default settings, the sentence "It costs $5 and $10 today" becomes math between the two dollar signs. Escape them as \$ or turn single-dollar math off. The remark-math readme documents the option, which defaults to true:
.use(remarkMath, {singleDollarTextMath: false})
In react-markdown, use the array form remarkPlugins={[[remarkMath, {singleDollarTextMath: false}]]}. Inline math then needs two or more dollars, as in $$x$$.
Before you wire anything up, you can check that your equations parse. Our editor's preview renders math with KaTeX, inline with $...$ and display with $$...$$, so a typo shows up right away:
For building a single equation with a symbol palette, the LaTeX equation editor renders with KaTeX 0.16 and copies a Markdown math snippet. For the LaTeX side of writing math, our Markdown equation guide covers the syntax.
Why Is My rehype-katex Output Broken? Four Fixes
Most broken output traces back to one of four causes:
- Unstyled or doubled math. The stylesheet is missing or comes from a different KaTeX version. Import
katex/dist/katex.min.cssand runnpm ls katex. - Red text where an equation should be. KaTeX couldn't parse the expression. Version 7 of the plugin doesn't throw: it records a message on the file, then renders error markup colored with the
errorColoroption (default#cc0000). Logfile.messagesto find the bad expression. \(...\)and\[...\]show up as plain brackets. remark-math only knows dollar signs, and Markdown treats the backslash as an escape, so you get(x^2)in the output. Feature request #120 for these delimiters is still open.ERR_REQUIRE_ESM. You're callingrequire('rehype-katex')on an older Node.js release. Switch toimport, or move to Node.js 22.12 or later, whererequire()loads ES modules by default.
If users write the Markdown, sanitize it too. Run rehype-sanitize before the math plugin and allow the math-inline and math-display classes on code elements. The rehype-katex readme has the exact schema.
One limitation applies whatever you fix: KaTeX supports a large subset of LaTeX, not all of it. Packages like TikZ and many document-level commands won't render, so check KaTeX's supported functions list when an expression fails for no obvious reason. Our KaTeX vs LaTeX comparison lists the LaTeX features KaTeX leaves out.
With rehype-katex in place, your Markdown math compiles to static KaTeX HTML that needs only one stylesheet in the browser. Keep KaTeX on a single version, import its CSS from the package, and decide early whether single dollars should mean math. To test an equation before it goes into your pipeline, paste it into the editor and watch the KaTeX preview update as you type.