mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-15 03:17:40 +01:00
Merge pull request #5553 from squidfunk/docs/math
Update math documentation
This commit is contained in:
Kathi
GitHub
commit
ecef1bcf82
198
docs/reference/math.md
Normal file
198
docs/reference/math.md
Normal file
@ -0,0 +1,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.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://cdn.jsdelivr.net/npm/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
|
||||
|
||||
|
||||
### 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
|
||||
extra_javascript:
|
||||
- javascripts/katex.js
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js # (1)!
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
|
||||
|
||||
extra_css:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
|
||||
```
|
||||
|
||||
1. Alternatively, you can add these JavaScript and CSS files via `script` tags by overriding HTML files.
|
||||
|
||||
|
||||
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
|
||||
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
|
||||
<script>
|
||||
window.MathJax = {
|
||||
tex: {
|
||||
inlineMath: [["\\(", "\\)"]],
|
||||
displayMath: [["\\[", "\\]"]],
|
||||
processEscapes: true,
|
||||
processEnvironments: true
|
||||
},
|
||||
options: {
|
||||
ignoreHtmlClass: ".*|",
|
||||
processHtmlClass: "arithmatex"
|
||||
}
|
||||
};
|
||||
</script>
|
||||
|
||||
|
||||
## 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.
|
||||
@ -1,120 +0,0 @@
|
||||
---
|
||||
icon: material/alphabet-greek
|
||||
---
|
||||
|
||||
# MathJax
|
||||
|
||||
[MathJax] is a beautiful and accessible way to display mathematical content
|
||||
in the browser, adds support for mathematical typesetting in different notations
|
||||
(e.g. [LaTeX], [MathML], [AsciiMath]), and can be easily integrated with
|
||||
Material for MkDocs.
|
||||
|
||||
[MathJax]: https://www.mathjax.org/
|
||||
[LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
|
||||
[MathML]: https://en.wikipedia.org/wiki/MathML
|
||||
[AsciiMath]: http://asciimath.org/
|
||||
|
||||
## Configuration
|
||||
|
||||
This configuration enables support for rendering block and inline block
|
||||
equations through [MathJax]. Create a configuration file and add the following
|
||||
lines to `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.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://cdn.jsdelivr.net/npm/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://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
|
||||
<script>
|
||||
window.MathJax = {
|
||||
tex: {
|
||||
inlineMath: [["\\(", "\\)"]],
|
||||
displayMath: [["\\[", "\\]"]],
|
||||
processEscapes: true,
|
||||
processEnvironments: true
|
||||
},
|
||||
options: {
|
||||
ignoreHtmlClass: ".*|",
|
||||
processHtmlClass: "arithmatex"
|
||||
}
|
||||
};
|
||||
</script>
|
||||
|
||||
## Usage
|
||||
|
||||
### Using block syntax
|
||||
|
||||
Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate
|
||||
lines:
|
||||
|
||||
``` latex title="MathJax, 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="MathJax, 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>
|
||||
@ -219,7 +219,7 @@ nav:
|
||||
- Icons, Emojis: reference/icons-emojis.md
|
||||
- Images: reference/images.md
|
||||
- Lists: reference/lists.md
|
||||
- MathJax: reference/mathjax.md
|
||||
- Math: reference/math.md
|
||||
- Tooltips: reference/tooltips.md
|
||||
- Insiders:
|
||||
- insiders/index.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user