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 with Material for MkDocs easily.

Configuration¶

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.

docs/javascripts/mathjax.js mkdocs.yml

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => { // (1)!
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

This integrates MathJax with instant loading.

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

See additional configuration options:

Arithmatex

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.

docs/javascripts/katex.js mkdocs.yml

document$.subscribe(({ body }) => { // (1)!
  renderMathInElement(body, {
    delimiters: [
      { left: "$$",  right: "$$",  display: true },
      { left: "$",   right: "$",   display: false },
      { left: "\\(", right: "\\)", display: false },
      { left: "\\[", right: "\\]", display: true }
    ],
  })
})

This integrates KaTeX with instant loading.

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - 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

Usage¶

Using block syntax¶

Blocks must be enclosed in $$...$$ or \[...\] on separate lines:

block syntax

$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$

\[ \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} \]

Using inline block syntax¶

Inline blocks must be enclosed in $...$ or $...$:

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)$.

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 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.