mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Documentation
This commit is contained in:
squidfunk
parent
e8504fdffb
commit
14d7874d0d
@ -4,10 +4,10 @@ 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
|
||||
[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/
|
||||
@ -19,14 +19,14 @@ with Material for MkDocs easily.
|
||||
|
||||
## Configuration
|
||||
|
||||
The following configuration enables support for rendering block and
|
||||
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
|
||||
[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`"
|
||||
@ -46,6 +46,9 @@ to your `mkdocs.yml`.
|
||||
};
|
||||
|
||||
document$.subscribe(() => { // (1)!
|
||||
MathJax.startup.output.clearCache()
|
||||
MathJax.typesetClear()
|
||||
MathJax.texReset()
|
||||
MathJax.typesetPromise()
|
||||
})
|
||||
```
|
||||
@ -72,11 +75,27 @@ See additional configuration options:
|
||||
[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>
|
||||
|
||||
### 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] 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`"
|
||||
@ -102,37 +121,16 @@ supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
|
||||
markdown_extensions:
|
||||
- pymdownx.arithmatex:
|
||||
generic: true
|
||||
|
||||
|
||||
extra_javascript:
|
||||
- javascripts/katex.js
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js # (1)!
|
||||
- javascripts/katex.js
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js
|
||||
- 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
|
||||
@ -159,44 +157,44 @@ $$
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
- __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.
|
||||
- __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.
|
||||
- __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.
|
||||
- __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.
|
||||
- __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
|
||||
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.
|
||||
|
||||
@ -53,11 +53,17 @@ of [additional JavaScript]:
|
||||
}
|
||||
};
|
||||
|
||||
document$.subscribe(() => {
|
||||
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
|
||||
@ -81,6 +87,7 @@ See reference for usage:
|
||||
[MathJax]: https://www.mathjax.org/
|
||||
[KaTeX]: https://github.com/Khan/KaTeX
|
||||
[additional JavaScript]: ../../customization.md#additional-javascript
|
||||
[instant loading]: ../setting-up-navigation.md#instant-loading
|
||||
[Using block syntax]: ../../reference/math.md#using-block-syntax
|
||||
[Using inline block syntax]: ../../reference/math.md#using-inline-block-syntax
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user