Skip to content

Commit ecef1bc

Browse files
katharinalisalinkatharinalisalin
authored
Merge pull request #5553 from squidfunk/docs/math
Update math documentation
2 parents 263a85d + 71ad6f5 commit ecef1bc

File tree

3 files changed

+199
-121
lines changed

3 files changed

+199
-121
lines changed

‎docs/reference/math.md

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

‎docs/reference/mathjax.md

-120
This file was deleted.

‎mkdocs.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ nav:
219219
- Icons, Emojis: reference/icons-emojis.md
220220
- Images: reference/images.md
221221
- Lists: reference/lists.md
222-
- MathJax: reference/mathjax.md
222+
- Math: reference/math.md
223223
- Tooltips: reference/tooltips.md
224224
- Insiders:
225225
- insiders/index.md

0 commit comments

Comments
 (0)