You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Nextra uses [KaTeX](https://katex.org/) to render LaTeX expressions directly in MDX.
6
+
Nextra can use [KaTeX](https://katex.org) to pre-render LaTeX expressions directly in MDX or [MathJax](https://mathjax.org) to
7
+
dynamically render math in the browser.
4
8
To enable LaTeX support, you must enable the `latex` option in your `next.config.mjs` file:
5
9
6
-
```js filename="next.config.mjs"
10
+
```js filename="next.config.mjs" {4}
7
11
importnextrafrom'nextra'
8
12
9
13
constwithNextra=nextra({
@@ -13,26 +17,42 @@ const withNextra = nextra({
13
17
exportdefaultwithNextra()
14
18
```
15
19
16
-
When enabled, KaTeX’s CSS and fonts will be automatically included in your site, and you can start writing math expressions in your MDX files. Using LaTeX within MDX is as simple as wrapping your expression in `$` or `$$`.
20
+
A value of `true{:js}` will use KaTeX as the math renderer. To explicitly specify the renderer, you may instead provide an
21
+
object `{ renderer: 'katex' }{:js}` or `{ renderer: 'mathjax' }{:js}` as the value to `latex: ...`.
22
+
23
+
When enabled, the required CSS and fonts will be automatically included in your site,
24
+
and you can start writing math expressions by enclosing inline math in `$...$` or display math in a `math`-labeled fenced code block:
25
+
26
+
~~~mdx
27
+
```math
28
+
\int x^2
29
+
```
30
+
~~~
17
31
18
32
## Example
19
33
20
34
For example, the following Markdown code:
21
35
22
-
```md filename="page.md"
23
-
The **Pythagorean equation**: $a=\sqrt{b^2 + c^2}$.
36
+
~~~md filename="page.md"
37
+
The **Pythagorean equation** is $a=\sqrt{b^2 + c^2}$ and the quadratic formula:
The **Pythagorean equation** is $a=\sqrt{b^2+c^2}$ and the quadratic formula:
48
+
49
+
```math
50
+
x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}
51
+
```
30
52
</div>
31
53
32
54
You can still use [Markdown and MDX syntax](../markdown) in the same line as your LaTeX expression.
33
55
34
-
import { Callout } from'nextra/components'
35
-
36
56
<Callout>
37
57
If you want to display `$` in your content instead of rendering it as an
38
58
equation, you can escape it with a backslash (`\`). For example `\$e = mc^2\$`
@@ -41,4 +61,116 @@ import { Callout } from 'nextra/components'
41
61
42
62
## API
43
63
44
-
To learn more about KaTeX and its supported functions and conventions, visit [KaTeX’s documentation](https://katex.org/docs/supported.html).
64
+
### KaTeX
65
+
66
+
`rehype-katex` is used to pre-render LaTeX expressions in your content. You can pass
67
+
supported [KaTeX options](https://katex.org/docs/options) via the `options` key in
68
+
your Nextra config. For example, to add a macro `\RR` that renders as `\mathbb{R}` you could
69
+
use the following configuration.
70
+
71
+
```js filename="next.config.mjs" {4-8}
72
+
constwithNextra=nextra({
73
+
latex: {
74
+
renderer:'katex',
75
+
options: {
76
+
macros: {
77
+
'\\RR':'\\mathbb{R}'
78
+
}
79
+
}
80
+
}
81
+
})
82
+
```
83
+
84
+
See [KaTeX’s documentation](https://katex.org/docs/supported) for a list of supported commands.
85
+
86
+
### MathJax
87
+
88
+
When MathJax is enabled (by setting `latex: { renderer: 'mathjax' }{:js}`) math is rendered on page load via
89
+
[`better-react-mathjax`](https://github.com/fast-reflexes/better-react-mathjax) instead of being pre-rendered.
90
+
By default, **MathJax is served via the MathJax CDN** instead of the files being directly included in your site.[^1]
91
+
92
+
[^1]: This can be changed by setting [`{ options: { src: ... } }{:js}`](https://github.com/fast-reflexes/better-react-mathjax#src-string--undefined) in the Nextra config.
93
+
94
+
MathJax rendering is enabled by setting `renderer: 'mathjax'{:js}` in your Nextra config.
95
+
96
+
```js filename="next.config.mjs" {3}
97
+
constwithNextra=nextra({
98
+
latex: {
99
+
renderer:'mathjax'
100
+
}
101
+
})
102
+
```
103
+
104
+
You can pass additional options to `better-react-mathjax` via the `options` key in your Nextra config. The `config: ...` option sets the
105
+
[MathJax configuration](https://docs.mathjax.org/en/latest/options/index.html). However, note that you can only pass serializable
106
+
options to `better-react-mathjax` via the `options` key in your Nextra config.[^2]
107
+
108
+
[^2]: To pass non-serializable objects like Functions, you must use the `<MathJaxContext config={...} />{:jsx}` component directly in your source.
109
+
110
+
For example, to configure MathJax to render `\RR` as `\mathbb{R}` you could use the following configuration.
111
+
112
+
```js filename="next.config.mjs" {4-12}
113
+
constwithNextra=nextra({
114
+
latex: {
115
+
renderer:'mathjax',
116
+
options: {
117
+
config: {
118
+
tex: {
119
+
macros: {
120
+
RR:'\\mathbb{R}'
121
+
}
122
+
}
123
+
}
124
+
}
125
+
}
126
+
})
127
+
```
128
+
129
+
#### MathJax CDN
130
+
131
+
By default, MathJax is served via the MathJax CDN. To serve files from another location (including locally in your project), you
132
+
must pass the `src: ...` option to the latex config. See the [better-react-mathjax documentation](https://github.com/fast-reflexes/better-react-mathjax#src-string--undefined)
133
+
for details about the `src` option. Additionally, you may need to copy the MathJax distribution into your `/public` folder for it to be served locally.
134
+
135
+
## KaTeX vs. MathJax
136
+
137
+
With KaTeX, math is pre-rendered which means flicker-free and faster page loads. However, KaTeX does not support all of the features
138
+
of MathJax, especially features related to accessibility.
139
+
140
+
The following two examples show the same formula rendered with KaTeX (first) and MathJax (second).
Because of MathJax's accessibility features, the second formula is tab-accessible and has a context menu that helps screen readers reprocess math for the visually impaired.
providedClassName===undefined// Give the option to the user to pass a falsy other than undefined to remove the default styles
57
57
? styled// Give the user a way to opt-in the default style provided with the theme. Probably remove this option in the next major version (v3.x) and just do a check to use the providedClassName or the default
0 commit comments