OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Documentation

Browse Source
This commit is contained in:
squidfunk 2024-01-20 08:53:16 +07:00
parent e8504fdffb
commit 14d7874d0d
No known key found for this signature in database
GPG Key ID: 5ED40BC4F9C436DF
2 changed files with 63 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
docs/reference/math.md
View File

@ -4,10 +4,10 @@ icon: material/alphabet-greek
# Math # Math
[MathJax] and [KaTeX] are two popular libraries for displaying [MathJax] and [KaTeX] are two popular libraries for displaying
mathematical content in browsers. Although both libraries offer similar mathematical content in browsers. Although both libraries offer similar
functionality, they use different syntaxes and have different configuration functionality, they use different syntaxes and have different configuration
options. This documentation site provides information on how to integrate them options. This documentation site provides information on how to integrate them
with Material for MkDocs easily. with Material for MkDocs easily.
[MathJax]: https://www.mathjax.org/ [MathJax]: https://www.mathjax.org/
@ -19,14 +19,14 @@ with Material for MkDocs easily.
## Configuration ## 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]. inline block equations using [MathJax] and [KaTeX].
### MathJax ### MathJax
[MathJax] is a powerful and flexible library that supports multiple input formats, [MathJax] is a powerful and flexible library that supports multiple input formats,
such as [LaTeX], [MathML], [AsciiMath], as well as various output formats like 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 HTML, SVG, MathML. To use MathJax within your project, add the following lines
to your `mkdocs.yml`. to your `mkdocs.yml`.
=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`" === ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
@ -46,6 +46,9 @@ to your `mkdocs.yml`.
}; };
document$.subscribe(() => { // (1)! document$.subscribe(() => { // (1)!
MathJax.startup.output.clearCache()
MathJax.typesetClear()
MathJax.texReset()
MathJax.typesetPromise() MathJax.typesetPromise()
}) })
``` ```
@ -72,11 +75,27 @@ See additional configuration options:
[Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex [Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
[instant loading]: ../setup/setting-up-navigation.md#instant-loading [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
[KaTeX] is a lightweight library that focuses on speed and simplicity. It [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 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`. [KaTeX] within your project, add the following lines to your `mkdocs.yml`.
=== ":octicons-file-code-16: `docs/javascripts/katex.js`" === ":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: markdown_extensions:
- pymdownx.arithmatex: - pymdownx.arithmatex:
generic: true generic: true
extra_javascript: extra_javascript:
- javascripts/katex.js - 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/katex.min.js
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
extra_css: extra_css:
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.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 ## Usage
### Using block syntax ### Using block syntax
@ -159,44 +157,44 @@ $$
Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`: Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
``` latex title="inline syntax" ``` latex title="inline syntax"
The homomorphism $f$ is injective if and only if its kernel is only the 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 singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$. that $f(a)=f(b)$.
``` ```
<div class="result" markdown> <div class="result" markdown>
The homomorphism $f$ is injective if and only if its kernel is only the 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 singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$. that $f(a)=f(b)$.
</div> </div>
## Comparing MathJax and KaTeX ## 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: consider:
- __Speed__: KaTeX is generally faster than MathJax. If your site requires rendering large - __Speed__: KaTeX is generally faster than MathJax. If your site requires
quantities of complex equations quickly, KaTeX may be the better choice. 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 - __Syntax Support__: MathJax supports a wider array of LaTeX commands and can
process a variety of mathematical markup languages (like AsciiMath and MathML). process a variety of mathematical markup languages (like AsciiMath and MathML).
If you need advanced LaTeX features, MathJax may be more suitable. If you need advanced LaTeX features, MathJax may be more suitable.
- __Output Format__: Both libraries support HTML and SVG outputs. However, - __Output Format__: Both libraries support HTML and SVG outputs. However,
MathJax also offers MathML output, which can be essential for accessibility, as MathJax also offers MathML output, which can be essential for accessibility,
it is readable by screen readers. as it is readable by screen readers.
- __Configurability__: MathJax provides a range of configuration options, - __Configurability__: MathJax provides a range of configuration options,
allowing for more precise control over its behavior. If you have specific allowing for more precise control over its behavior. If you have specific
rendering requirements, MathJax might be a more flexible choice. rendering requirements, MathJax might be a more flexible choice.
- __Browser Support__: While both libraries work well in modern browsers, - __Browser Support__: While both libraries work well in modern browsers,
MathJax has broader compatibility with older browsers. If your audience uses a MathJax has broader compatibility with older browsers. If your audience uses a
variety of browsers, including older ones, MathJax might be a safer option. variety of browsers, including older ones, MathJax might be a safer option.
In summary, KaTeX shines with its speed and simplicity, whereas MathJax offers In summary, KaTeX shines with its speed and simplicity, whereas MathJax offers
more features and better compatibility at the expense of speed. The choice more features and better compatibility at the expense of speed. The choice
between the two will largely depend on your specific needs and constraints. between the two will largely depend on your specific needs and constraints.

9
docs/setup/extensions/python-markdown-extensions.md
View File

@ -53,11 +53,17 @@ of [additional JavaScript]:
} }
}; };
document$.subscribe(() => { document$.subscribe(() => { // (1)!
MathJax.startup.output.clearCache()
MathJax.typesetClear()
MathJax.texReset()
MathJax.typesetPromise() MathJax.typesetPromise()
}) })
``` ```
1. This integrates MathJax with [instant loading]
=== ":octicons-file-code-16: `mkdocs.yml`" === ":octicons-file-code-16: `mkdocs.yml`"
``` yaml ``` yaml
@ -81,6 +87,7 @@ See reference for usage:
[MathJax]: https://www.mathjax.org/ [MathJax]: https://www.mathjax.org/
[KaTeX]: https://github.com/Khan/KaTeX [KaTeX]: https://github.com/Khan/KaTeX
[additional JavaScript]: ../../customization.md#additional-javascript [additional JavaScript]: ../../customization.md#additional-javascript
[instant loading]: ../setting-up-navigation.md#instant-loading
[Using block syntax]: ../../reference/math.md#using-block-syntax [Using block syntax]: ../../reference/math.md#using-block-syntax
[Using inline block syntax]: ../../reference/math.md#using-inline-block-syntax [Using inline block syntax]: ../../reference/math.md#using-inline-block-syntax