From 3bd214fce62741ea42123475f0ebd7ba2f837b75 Mon Sep 17 00:00:00 2001 From: Anurag Dhadse Date: Sat, 29 Apr 2023 19:24:30 +0530 Subject: [PATCH 1/3] added katex documentation --- docs/reference/katex.md | 70 +++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 71 insertions(+) create mode 100644 docs/reference/katex.md diff --git a/docs/reference/katex.md b/docs/reference/katex.md new file mode 100644 index 000000000..a07c1baba --- /dev/null +++ b/docs/reference/katex.md @@ -0,0 +1,70 @@ +--- +icon: material/alphabet-greek +--- + +# MathJax + +[KaTeX] is a Lightning-fast library to display mathematical expressions +in the browser. + + [KaTeX]: https://katex.org/ + +KaTeX isn't supported by default, but can be easily integrated with Material for MkDocs. + +## Configuration + +This configuration enables support for rendering block and inline block +equations through [KaTex]. Create a configuration file and add the following +lines to `mkdocs.yml`: + +=== ":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 MathJax with [instant loading]. + +=== ":octicons-file-code-16: `overrides/main.html`" + + ```html + {% extends "base.html" %} + + {% block libs %} + + + + + + {{ super() }} + {% endblock %} + ``` + +=== ":octicons-file-code-16: `mkdocs.yml`" + + ``` yaml + extra_javascript: + - javascripts/katex.js + ``` + + [instant loading]: ../setup/setting-up-navigation.md#instant-loading + +## Usage + +### Using block syntax + +Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate +lines. + +### Using inline block syntax + +Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 25f00ac59..a62260d81 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -220,6 +220,7 @@ nav: - Images: reference/images.md - Lists: reference/lists.md - MathJax: reference/mathjax.md + - KaTeX: reference/katex.md - Tooltips: reference/tooltips.md - Insiders: - insiders/index.md From c1948b22ea3d46716b1e384268235e0d7390ac5a Mon Sep 17 00:00:00 2001 From: Anurag Dhadse Date: Sat, 13 May 2023 17:04:57 +0530 Subject: [PATCH 2/3] moved katex documentation to math.md --- docs/reference/katex.md | 70 -------------------------- docs/reference/{mathjax.md => math.md} | 39 ++++++++++++-- mkdocs.yml | 3 +- 3 files changed, 37 insertions(+), 75 deletions(-) delete mode 100644 docs/reference/katex.md rename docs/reference/{mathjax.md => math.md} (71%) diff --git a/docs/reference/katex.md b/docs/reference/katex.md deleted file mode 100644 index a07c1baba..000000000 --- a/docs/reference/katex.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -icon: material/alphabet-greek ---- - -# MathJax - -[KaTeX] is a Lightning-fast library to display mathematical expressions -in the browser. - - [KaTeX]: https://katex.org/ - -KaTeX isn't supported by default, but can be easily integrated with Material for MkDocs. - -## Configuration - -This configuration enables support for rendering block and inline block -equations through [KaTex]. Create a configuration file and add the following -lines to `mkdocs.yml`: - -=== ":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 MathJax with [instant loading]. - -=== ":octicons-file-code-16: `overrides/main.html`" - - ```html - {% extends "base.html" %} - - {% block libs %} - - - - - - {{ super() }} - {% endblock %} - ``` - -=== ":octicons-file-code-16: `mkdocs.yml`" - - ``` yaml - extra_javascript: - - javascripts/katex.js - ``` - - [instant loading]: ../setup/setting-up-navigation.md#instant-loading - -## Usage - -### Using block syntax - -Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate -lines. - -### Using inline block syntax - -Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`. \ No newline at end of file diff --git a/docs/reference/mathjax.md b/docs/reference/math.md similarity index 71% rename from docs/reference/mathjax.md rename to docs/reference/math.md index f41074402..0d9483127 100644 --- a/docs/reference/mathjax.md +++ b/docs/reference/math.md @@ -6,13 +6,14 @@ icon: material/alphabet-greek [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 +(e.g. [LaTeX], [MathML], [AsciiMath], [KaTeX]), 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/ + [KaTeX]: https://katex.org/ ## Configuration @@ -43,7 +44,24 @@ lines to `mkdocs.yml`: 1. This integrates MathJax with [instant loading]. -=== ":octicons-file-code-16: `mkdocs.yml`" +=== ":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" ``` yaml markdown_extensions: @@ -51,11 +69,26 @@ 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" + + ``` 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. 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.