1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
---
icon: material/alphabet-greek
---
# Math
[MathJax] and [KaTeX] are two popular libraries for displaying
mathematical content in browsers. Although both libraries offer similar
functionality, they use different syntaxes and have different configuration
options. This documentation site provides information on how to integrate them
with Material for MkDocs easily.
[MathJax]: https://www.mathjax.org/
[LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
[MathML]: https://en.wikipedia.org/wiki/MathML
[AsciiMath]: http://asciimath.org/
[KaTeX]: https://katex.org/
## Configuration
The following configuration enables support for rendering block and
inline block equations using [MathJax] and [KaTeX].
### MathJax
[MathJax] is a powerful and flexible library that supports multiple input formats,
such as [LaTeX], [MathML], [AsciiMath], as well as various output formats like
HTML, SVG, MathML. To use MathJax within your project, add the following lines
to your `mkdocs.yml`.
=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
``` js
window.MathJax = {
tex: {
inlineMath: [["\\(", "\\)"]],
displayMath: [["\\[", "\\]"]],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: ".*|",
processHtmlClass: "arithmatex"
}
};
document$.subscribe(() => { // (1)!
MathJax.startup.output.clearCache()
MathJax.typesetClear()
MathJax.texReset()
MathJax.typesetPromise()
})
```
1. This integrates MathJax with [instant loading].
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
markdown_extensions:
- pymdownx.arithmatex:
generic: true
extra_javascript:
- javascripts/mathjax.js
- https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
```
See additional configuration options:
- [Arithmatex]
[Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
<script id="MathJax-script" async src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
<script>
window.MathJax = {
tex: {
inlineMath: [["\\(", "\\)"]],
displayMath: [["\\[", "\\]"]],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: ".*|",
processHtmlClass: "arithmatex"
}
};
</script>
### KaTeX
[KaTeX] is a lightweight library that focuses on speed and simplicity. It
supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
[KaTeX] within your project, add the following lines to your `mkdocs.yml`.
=== ":octicons-file-code-16: `docs/javascripts/katex.js`"
``` js
document$.subscribe(({ body }) => { // (1)!
renderMathInElement(body, {
delimiters: [
{ left: "$$", right: "$$", display: true },
{ left: "$", right: "$", display: false },
{ left: "\\(", right: "\\)", display: false },
{ left: "\\[", right: "\\]", display: true }
],
})
})
```
1. This integrates KaTeX with [instant loading].
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
markdown_extensions:
- pymdownx.arithmatex:
generic: true
extra_javascript:
- javascripts/katex.js
- https://unpkg.com/katex@0/dist/katex.min.js
- https://unpkg.com/katex@0/dist/contrib/auto-render.min.js
extra_css:
- https://unpkg.com/katex@0/dist/katex.min.css
```
## Usage
### Using block syntax
Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate
lines:
``` latex title="block syntax"
$$
\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
$$
```
<div class="result" markdown>
$$
\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
$$
</div>
### Using inline block syntax
Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
``` latex title="inline syntax"
The homomorphism $f$ is injective if and only if its kernel is only the
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$.
```
<div class="result" markdown>
The homomorphism $f$ is injective if and only if its kernel is only the
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$.
</div>
## Comparing MathJax and KaTeX
When deciding between MathJax and KaTeX, there are several key factors to
consider:
- __Speed__: KaTeX is generally faster than MathJax. If your site requires
rendering large quantities of complex equations quickly, KaTeX may be the
better choice.
- __Syntax Support__: MathJax supports a wider array of LaTeX commands and can
process a variety of mathematical markup languages (like AsciiMath and MathML).
If you need advanced LaTeX features, MathJax may be more suitable.
- __Output Format__: Both libraries support HTML and SVG outputs. However,
MathJax also offers MathML output, which can be essential for accessibility,
as it is readable by screen readers.
- __Configurability__: MathJax provides a range of configuration options,
allowing for more precise control over its behavior. If you have specific
rendering requirements, MathJax might be a more flexible choice.
- __Browser Support__: While both libraries work well in modern browsers,
MathJax has broader compatibility with older browsers. If your audience uses a
variety of browsers, including older ones, MathJax might be a safer option.
In summary, KaTeX shines with its speed and simplicity, whereas MathJax offers
more features and better compatibility at the expense of speed. The choice
between the two will largely depend on your specific needs and constraints.
|
