diff --git a/docs/reference/math.md b/docs/reference/math.md
index 0d9483127..92744158e 100644
--- a/docs/reference/math.md
+++ b/docs/reference/math.md
@@ -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 `
+
## 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)$.
+
+
+## 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.