Improved math documentation

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
+[MathJax] and [KaTeX] are two popular libraries for displaying 
-in the browser, adds support for mathematical typesetting in different notations
+mathematical content in browsers. Although both libraries offer similar 
-(e.g. [LaTeX], [MathML], [AsciiMath], [KaTeX]), and can be easily integrated with
+functionality, they use different syntaxes and have different configuration 
-Material for MkDocs.
+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
+The following configuration enables support for rendering block and 
-equations through [MathJax]. Create a configuration file and add the following
+inline block equations using [MathJax] and [KaTeX].
-lines to `mkdocs.yml`:
+
+### 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`"
+=== ":octicons-file-code-16: `mkdocs.yml`"
-
-    ``` 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"
 
     ``` yaml
     markdown_extensions:
@@ -74,7 +65,38 @@ lines to `mkdocs.yml`:
       - 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.