mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-12 01:50:52 +01:00
Improved math documentation
This commit is contained in:
katharinalisalin
parent
a154c64028
commit
71ad6f508a
@ -2,12 +2,13 @@
|
||||
icon: material/alphabet-greek
|
||||
---
|
||||
|
||||
# MathJax
|
||||
# Math
|
||||
|
||||
[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], [KaTeX]), and can be easily integrated with
|
||||
Material for MkDocs.
|
||||
[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
|
||||
@ -15,11 +16,18 @@ Material for MkDocs.
|
||||
[AsciiMath]: http://asciimath.org/
|
||||
[KaTeX]: https://katex.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`:
|
||||
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`"
|
||||
|
||||
@ -44,24 +52,7 @@ lines to `mkdocs.yml`:
|
||||
|
||||
1. This integrates MathJax with [instant loading].
|
||||
|
||||
=== ":octicons-file-code-16: `docs/javascripts/katex.js`"
|
||||
|
||||
``` js
|
||||
document$.subscribe(() => { // (1)!
|
||||
renderMathInElement(document.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` for MathJax"
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -69,12 +60,43 @@ lines to `mkdocs.yml`:
|
||||
generic: true
|
||||
|
||||
extra_javascript:
|
||||
- javascripts/mathjax.js
|
||||
- javascripts/mathjax.js
|
||||
- https://polyfill.io/v3/polyfill.min.js?features=es6
|
||||
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml` for KaTeX"
|
||||
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:
|
||||
@ -86,16 +108,9 @@ lines to `mkdocs.yml`:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
|
||||
```
|
||||
|
||||
1. Or you can adgitd these JS/CSS via `<script>` tag by overriding HTML files.
|
||||
1. Alternatively, you can add these JavaScript and CSS files via `script` tags by overriding HTML files.
|
||||
|
||||
|
||||
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>
|
||||
@ -113,6 +128,7 @@ See additional configuration options:
|
||||
};
|
||||
</script>
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
### Using block syntax
|
||||
@ -120,7 +136,7 @@ See additional configuration options:
|
||||
Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate
|
||||
lines:
|
||||
|
||||
``` latex title="MathJax, block syntax"
|
||||
``` latex title="block syntax"
|
||||
$$
|
||||
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
|
||||
$$
|
||||
@ -138,7 +154,7 @@ $$
|
||||
|
||||
Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
|
||||
|
||||
``` latex title="MathJax, inline syntax"
|
||||
``` 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)$.
|
||||
@ -151,3 +167,32 @@ 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user