diff --git a/docs/reference/math.md b/docs/reference/math.md index 01aa4ad1a..d6d7fa5a5 100644 --- a/docs/reference/math.md +++ b/docs/reference/math.md @@ -4,10 +4,10 @@ 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 +[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/ @@ -19,14 +19,14 @@ with Material for MkDocs easily. ## 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]. ### 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 +[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`" @@ -46,6 +46,9 @@ to your `mkdocs.yml`. }; document$.subscribe(() => { // (1)! + MathJax.startup.output.clearCache() + MathJax.typesetClear() + MathJax.texReset() MathJax.typesetPromise() }) ``` @@ -72,11 +75,27 @@ See additional configuration options: [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] 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`" @@ -102,37 +121,16 @@ supports a subset of LaTeX syntax and can render math to HTML and SVG. To use markdown_extensions: - pymdownx.arithmatex: generic: true - + extra_javascript: - - javascripts/katex.js - - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js # (1)! + - javascripts/katex.js + - 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 - + 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 @@ -159,44 +157,44 @@ $$ 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 +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 +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 +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. +- __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. +- __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. +- __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. +- __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. +- __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 +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/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 82e71f983..42f669f04 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -53,11 +53,17 @@ of [additional JavaScript]: } }; - document$.subscribe(() => { + document$.subscribe(() => { // (1)! + MathJax.startup.output.clearCache() + MathJax.typesetClear() + MathJax.texReset() MathJax.typesetPromise() }) ``` + 1. This integrates MathJax with [instant loading] + + === ":octicons-file-code-16: `mkdocs.yml`" ``` yaml @@ -81,6 +87,7 @@ See reference for usage: [MathJax]: https://www.mathjax.org/ [KaTeX]: https://github.com/Khan/KaTeX [additional JavaScript]: ../../customization.md#additional-javascript + [instant loading]: ../setting-up-navigation.md#instant-loading [Using block syntax]: ../../reference/math.md#using-block-syntax [Using inline block syntax]: ../../reference/math.md#using-inline-block-syntax