From 71ad6f508a136a9e99ef864c8ac2c342aac57f13 Mon Sep 17 00:00:00 2001 From: katharinalisalin Date: Tue, 23 May 2023 17:30:23 +0200 Subject: [PATCH] Improved math documentation --- docs/reference/math.md | 121 ++++++++++++++++++++++++++++------------- 1 file changed, 83 insertions(+), 38 deletions(-) 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.