🧩 The KaTeX Plugin is a DokuWiki plugin for parsing TeX expressions and rendering them into math/chemical equations with KaTeX and mhchem.

• PHP >= 7.4

There're about 3 methods to install an extension on your DokuWiki instance:

• Method 01 — Search and install the plugin using the Extension Manager.
• Method 02 — Download the extension and unpack it into <DOKUWIKI_DIR>/lib/plugins/katex on your server.
• Method 03 — Maintain and install with DokuWiki Command Line Tools.

Example of installing with DokuWiki Command Line Tools:

# Install KaTeX plugin via Git.
$ ./bin/gittool.php clone katex
 
# The same as clone, but install via download when no git source can be found.
$ ./bin/gittool.php install katex

TeX/LaTeX allows two writing modes for mathematical expression. Let's take an example from Overleaf Documentation:

To render the example above in your DokuWiki instance with the KaTeX plugin for DokuWiki installed, the pagesource would be:

Typeset mathematics contained inline (within) with the text of a paragraph needs to
take less space than the same math typeset outside the paragraph text as standalone,
display-style, material. To see this in practice, let’s explain that the equation 
$f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x}$ may diverge or converge depending on the
value of $x$. We can also typeset $f(x)$ outside the paragraph in display style:

$$f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x}$$

With the default configuration of the delimiters:

• Inline Mode use the syntax like $<EXPRESSION>$ or \(<EXPRESSION>\)$.
• Display Mode use the syntax like $$<EXPRESSION>$$ or \[<EXPRESSION>\].

Besides, delimiters with space or newline are available:

Delimiters with space:

$ f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x} $

$$ f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x} $$

\( f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x} \)

\[ f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x} \]

Delimiters with newline:

$
f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x}
$

$$
f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x}
$$

\(
f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x}
\)

\[
f(x) = \sum_{i=0}^{n} \frac{a_i}{1+x}
\]

To type chemical equations, the mhchem extension must be enabled.

Chemical Equations (ce)

$\ce{CO2 + C -> 2 CO}$

$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$

$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$

Chemical Formulae and Charges

$\ce{H2O}$

$\ce{Sb2O3}$

$\ce{H+}$
 
$\ce{CrO4^2-}$
 
$\ce{[AgCl2]-}$
 
$\ce{Y^99+}$
 
$\ce{Y^{99+}}$

Check more examples on mhchem for MathJax/KaTeX.

You can choose to host KaTeX resource files on your server or deliver them by one of the following CDN (Content Delivery Network) providers:

Note
The KaTeX plugin for DokuWiki will contain the latest version of KaTeX from its release page.

The KaTeX plugin for DokuWiki supports some of the extensions provided by KaTeX for improving user experiences and additional functions:

You can enable or disable them from the Configuration Settings page on your DokuWiki site.

The KaTeX plugin for DokuWiki allows you to customize some of the rendering options of KaTeX:

• HTML outputs KaTeX in HTML only.
• MathML outputs KaTeX in MathML only.
• HTML and MathML outputs HTML for visual rendering and includes MathML for accessibility.

Example

{ "left": "$$", "right": "$$", "display": true }
{ "left": "$", "right": "$", "display": false }
{ "left": "\(", "right": "\)", "display": false }
{ "left": "\[", "right": "\]", "display": true }

Explanation

• Each line can only contain one delimiter, and there is no need to add a comma at the end.
• Each delimiter has three properties.
  • left: a string which starts the math expression (the left delimiter)
  • right: a string which ends the math expression (the right delimiter)
  • display: a boolean of whether the math in the expression should be rendered in display mode or not.
• Each delimiter should satisfy the JSON format, and double quotes should be used instead of single quotes when representing strings.
• The order of line matters.

Example

script, noscript, style, textarea, pre, code, option

Explanation

• Each tag should be separated with comma in one line.

Example

code-mirror, annotation-box

Explanation

• Each class should be separated with comma in one line.

Example

#CCDDFF
#719

Explanation

• The color string should be given in Hex3 (#XXX) or HEX6 (#XXXXXX) format.

Example

{ "command": "\NN", "expansion": "\mathbb{N}" }
{ "command": "\ZZ", "expansion": "\mathbb{Z}" }
{ "command": "\QQ", "expansion": "\mathbb{Q}" }
{ "command": "\RR", "expansion": "\mathbb{R}" }
{ "command": "\CC", "expansion": "\mathbb{C}" }

Explanation

• Each line can only contain one macro, and there is no need to add a comma at the end.
• Each macro has two properties.
  • command: a string as the name for mapping to the expansion.
  • expansion: a string that describes the expansion of the macro.
• Each macro should satisfy the JSON format, and double quotes should be used instead of single quotes when representing strings.

The following DokuWiki sites use the KaTeX plugin:

• thetechbasement.no (nuclear physics, programming)

Note
If you're using KaTeX plugin on your DokuWiki instance, feel free to add it to the list 😊.

To render equations with KaTeX, escaping the $ character in a sentence is always a challenge. To handle it completely, I might need to replace the syntax with a more complex format like <math>EXPRESSION</math>, but that’s undeniably cumbersome.

Therefore, in the settings of the KaTeX plugin for DokuWiki, I provide users with additional configuration options to change the rendering delimiters. I suggest to modify the settings as below to avoid using $ EXPRESSION $ and $$ EXPRESSION $$ for rendering. And use just \( EXPRESSION \) and \[ EXPRESSION \] instread.

{ "left": "\(", "right": "\)", "display": false }
{ "left": "\[", "right": "\]", "display": true }

After all, the likelihood of encountering \( … \) in a sentence is much lower than the $ … $.

Licensed under the GPL-3.0 License, Copyright © 2023-present H.-H. PENG (Hsins).