diff --git a/docs/reference/math.md b/docs/reference/math.md new file mode 100644 index 000000000..92744158e --- /dev/null +++ b/docs/reference/math.md @@ -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. + + + + + + + +## 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{.}} +$$ +``` + +
+ +$$ +\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} +$$ + +
+ +### 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)$. +``` + +
+ +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)$. + +
+ + +## 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. diff --git a/docs/reference/mathjax.md b/docs/reference/mathjax.md deleted file mode 100644 index f41074402..000000000 --- a/docs/reference/mathjax.md +++ /dev/null @@ -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 - - - - - -## 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{.}} -$$ -``` - -
- -$$ -\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} -$$ - -
- -### 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)$. -``` - -
- -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)$. - -
diff --git a/mkdocs.yml b/mkdocs.yml index 440c64bae..8d8c21ff2 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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