Table of Contents
KaTeX Plugin
Compatible with DokuWiki
- 2024-02-06 "Kaos" unknown
- 2023-04-04 "Jack Jackrum" yes
- 2022-07-31 "Igor" unknown
- 2020-07-29 "Hogfather" unknown
Overview
🧩 The KaTeX Plugin is a DokuWiki plugin for parsing TeX expressions and rendering them into math/chemical equations with KaTeX and mhchem.
Requirements
- PHP >= 7.4
Installation
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
Usage and Examples
Mathematical Modes
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} \]
Chemical Equations
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.
Configuration and Settings
Resources Hosting
You can choose to host KaTeX resource files on your server or deliver them by one of the following CDN (Content Delivery Network) providers:
Options | Description |
---|---|
Self-hosted | Host the minified files on your own DokuWiki instance. Files will contained with the KaTeX plugin for Dokuwiki. |
BootCDN | BootCDN is the free CDN service maintained by Bootstrap China and hosted by Jitu Cloud. |
cdnjs | cdnjs is a free and open-source CDN service trusted and used by over 12.5% of all websites, powered by Cloudflare. |
UNPKG | UNPKG is a fast, global CDN service for everything on npm, powered by Cloudflare. |
jsDelivr | JsDelivr is a free CDN service for open source files. There're no bandwidth limits or premium features and it's completely free to use by anybody. |
jsHub | jsHub is an open source project dedicated to for providing stable, fast and free CDN service. The packages are mainly synchronized with the cdnjs repository. |
Staticfile CDN | Staticfile CDN provide stable and fast CDN service in China. Powered by Quniu Cloud and supported by Juejin Community |
Note
The KaTeX plugin for DokuWiki will contain the latest version of KaTeX from its release page.
Extensions
The KaTeX plugin for DokuWiki supports some of the extensions provided by KaTeX for improving user experiences and additional functions:
Configuration | Explanation |
---|---|
extension-copy-tex | When selecting and copying KaTeX-rendered elements, copies their TeX expressions to the clipboard |
extension-mhchem | Write beautiful chemical equations easily. |
You can enable or disable them from the Configuration Settings page on your DokuWiki site.
Rendering Options
The KaTeX plugin for DokuWiki allows you to customize some of the rendering options of KaTeX:
Configuration | Explanation |
---|---|
option-output | The markup language of the rendering output. |
option-delimiters | List of delimiters to look for expressions, processed in the same order as the list. |
option-ignored-tags | List of types of DOM node to ignore when recursing through. |
option-ignored-classes | List of class names of DOM node to ignore when recursing through. |
option-throwonerror | Throw a ParseError when it encounters an unsupported command or invalid LaTeX syntax; Else, KaTeX will render unsupported commands as text by given color. |
option-error-color | The color that unsupported commands and invalid LaTeX syntax are rendered in when throwonerror is disabled. |
option-macros | Collection of custom macros. Each macro maps a command to given expansion. |
Configuration: output
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.
Configuration: delimiters
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.
Configuration: ignored-tags
Example
script, noscript, style, textarea, pre, code, option
Explanation
- Each tag should be separated with comma in one line.
Configuration: ignored-classes
Example
code-mirror, annotation-box
Explanation
- Each class should be separated with comma in one line.
Configuration: error-color
Example
#CCDDFF #719
Explanation
- The color string should be given in Hex3 (
#XXX
) or HEX6 (#XXXXXX
) format.
Configuration: macros
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.
Sreenshots and Demo Sites
Screenshots
Rendering (pagesource) | Configuration |
---|---|
![]() | ![]() |
Demo Sites
The following DokuWiki sites use the KaTeX plugin:
Note
If you're using KaTeX plugin on your DokuWiki instance, feel free to add it to the list 😊.
License
Licensed under the GPL-3.0 License, Copyright © 2023-present H.-H. PENG (Hsins).