mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-12-25 22:04:52 +01:00
0de8be26f8
This is consistent with how we fetch Mermaid.js and automatically picks the latest minor version.
201 lines
5.8 KiB
Markdown
201 lines
5.8 KiB
Markdown
---
|
|
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://polyfill.io/v3/polyfill.min.js?features=es6
|
|
- 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 src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
|
|
<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"
|
|
$$
|
|
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
|
|
$$
|
|
```
|
|
|
|
<div class="result" markdown>
|
|
|
|
$$
|
|
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
|
|
$$
|
|
|
|
</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.
|