1<!-- badges --> 2<div align="right"> 3 4 [![](https://img.shields.io/github/license/Hsins/dokuwiki-plugin-katex.svg?label=License&style=flat-square)](./LICENSE) 5 6</div> 7 8<!-- logo, title and description --> 9<div align="center"> 10 11 <img src="https://user-images.githubusercontent.com/26391143/232232798-db6f3b58-839a-4ab8-9b3f-4a3b82af900d.png" alt="DokuWiki Plugin: KaTeX" height="150px" /> 12 13# DokuWiki Plugin: KaTeX 14 15 _DokuWiki plugin for parsing_ $\TeX{}$ _expressions and rendering them to math/chemical equations with [KaTeX](https://katex.org/) and [mhchem](https://mhchem.github.io/MathJax-mhchem/)._ 16 17[![Plugin Page](https://img.shields.io/badge/PLUGIN%20PAGE--f5edcc.svg?logo=read-the-docs&style=flat-square)](https://www.dokuwiki.org/plugin:katex) 18[![](https://img.shields.io/badge/CHANGELOG--E08B32.svg?logo=git&style=flat-square)](./CHANGELOG.md) 19 20</div> 21 22## Installation 23 24There're roughly different 3 methods to install an extension on your DokuWiki instance: 25 26- **Method 01** — Search and install the plugin using the [Extension Manager](https://www.dokuwiki.org/plugin:extension). 27- **Method 02** — Download the extension and unpack it into `<DOKUWIKI_DIR>/lib/plugins/katex` on your server. 28- **Method 03** — Maintain and install with [DokuWiki Command Line Tools](https://www.dokuwiki.org/plugin:cli). 29 30Example of installing with DokuWiki Command Line Tools: 31 32``` bash 33# Install KaTeX plugin via Git. 34$ ./bin/gittool.php clone katex 35 36# The same as clone, but install via download when no git source can be found. 37$ ./bin/gittool.php install katex 38``` 39 40## Configuration and Settings 41 42### Resources Hosting 43 44You can choose to host KaTeX resource files on your server or deliver them by one of the following CDN (Content Delivery Network) providers: 45 46| Options | Description | 47| :---------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 48| Self-hosted | Host the minified files on your own DokuWiki instance. Files will contained with the KaTeX plugin for Dokuwiki. | 49| [BootCDN](https://www.bootcdn.cn/) | BootCDN is the free CDN service maintained by [Bootstrap China](https://www.bootcss.com/) and hosted by [Jitu Cloud](https://www.jitucdn.com/). | 50| [cdnjs](https://cdnjs.com/) | cdnjs is a free and open-source CDN service trusted and used by over 12.5% of all websites, powered by Cloudflare. | 51| [UNPKG](https://www.unpkg.com/) | UNPKG is a fast, global CDN service for everything on npm, powered by Cloudflare. | 52| [jsDelivr](https://www.jsdelivr.com/) | 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. | 53| [jsHub](https://jshub.com/) | jsHub is an open source project dedicated to for providing stable, fast and free CDN service. The packages are mainly synchronized with the [cdnjs](https://github.com/cdnjs/cdnjs) repository. | 54| [Staticfile CDN](https://staticfile.org/) | Staticfile CDN provide stable and fast CDN service in China. Powered by [Quniu Cloud](http://qiniu.com/) and supported by [Juejin Community](https://juejin.cn/). | 55 56> **Note** The KaTeX plugin for DokuWiki contain the latest version of KaTeX from its [release page](https://github.com/KaTeX/KaTeX/releases). 57 58### Extensions 59 60The KaTeX plugin for DokuWiki supports some of the [extensions](https://katex.org/docs/libs.html) provided by KaTeX for improving user experiences and additional functions: 61 62| Configuration | Explanation | 63| :------------------: | :------------------------------------------------------------------------------------------------------------- | 64| `extension-copy-tex` | If enabled, when selecting and copying KaTeX-rendered elements, copies their TeX expressions to the clipboard. | 65| `extension-mhchem` | If enabled, you can write beautiful chemical equations easily. | 66 67You can enable or disable them from the Configuration Settings page on your DokuWiki site. 68 69### Rendering Options 70 71The KaTeX plugin for DokuWiki allows you to customize some of the rendering [options](https://katex.org/docs/options.html) of KaTeX: 72 73| Configuration | Explanation | 74| :----------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | 75| `option-output` | The markup language of the rendering output. | 76| `option-delimiters` | List of delimiters to look for expressions, processed in the same order as the list. | 77| `option-ignored-tags` | List of types of DOM node to ignore when recursing through. | 78| `option-ignored-classes` | List of class names of DOM node to ignore when recursing through. | 79| `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. | 80| `option-error-color` | The color that unsupported commands and invalid $\LaTeX{}$ syntax are rendered in when `throwonerror` is disabled. | 81| `option-macros` | Collection of custom macros. Each macro maps a command to given expansion. | 82 83#### Configuration: `option-output` 84 85- `HTML` outputs KaTeX in HTML only. 86- `MathML` outputs KaTeX in MathML only. 87- `HTML and MathML` outputs HTML for visual rendering and includes MathML for accessibility. 88 89#### Configuration: `option-delimiters` 90 91**Example** 92 93``` plain 94{ "left": "$$", "right": "$$", "display": true } 95{ "left": "$", "right": "$", "display": false } 96{ "left": "\(", "right": "\)", "display": false } 97{ "left": "\[", "right": "\]", "display": true } 98``` 99 100**Explanation** 101 102- Each line can only contain one delimiter, and there is no need to add a comma at the end. 103- Each delimiter has three properties. 104 - `left`: a **string** which starts the math expression (the left delimiter) 105 - `right`: a **string** which ends the math expression (the right delimiter) 106 - `display`: a **boolean** of whether the math in the expression should be rendered in display mode or not. 107- Each delimiter should satisfy the [JSON](http://www.json.org/) format, and double quotes should be used instead of single quotes when representing strings. 108- The order of line matters. 109 110#### Configuration: `option-ignored-tags` 111 112**Example** 113 114``` plain 115script, noscript, style, textarea, pre, code, option 116``` 117 118**Explanation** 119 120- Each tag should be separated with comma in one line. 121 122#### Configuration: `option-ignored-classes` 123 124**Exmaple** 125 126``` plain 127code-mirror, annotation-box 128``` 129 130**Explanation** 131 132- Each class should be separated with comma in one line. 133 134#### Configuration: `option-error-color` 135 136**Example** 137 138``` plain 139#CCDDFF 140#719 141``` 142 143**Explanation** 144 145- The color string should be given in HEX3 (`#XXX`) or HEX6 (`#XXXXXX`) format. 146 147#### Configuration: `option-macros` 148 149**Example** 150 151``` plain 152{ "command": "\NN", "expansion": "\mathbb{N}" } 153{ "command": "\ZZ", "expansion": "\mathbb{Z}" } 154{ "command": "\QQ", "expansion": "\mathbb{Q}" } 155{ "command": "\RR", "expansion": "\mathbb{R}" } 156{ "command": "\CC", "expansion": "\mathbb{C}" } 157``` 158 159**Explanation** 160 161- Each line can only contain one macro, and there is no need to add a comma at the end. 162- Each macro has two properties: 163 - `command`: a **string** as the name for mapping to the expansion. 164 - `expansion`: a **string** that describes the expansion of the macro. 165- Each macro should satisfy the [JSON](http://www.json.org/) format, and double quotes should be used instead of single quotes when representing strings. 166 167## Sreenshots and Demo Sites 168 169### Screenshots 170 171<table> 172<tr> 173 <th> Rendering </th> 174 <th> Configuration </th> 175</tr> 176<tr> 177<td align="center"> 178 179![image](https://user-images.githubusercontent.com/26391143/232169170-80e367da-a854-473e-a017-1dc50b5ea1d8.png) 180 181</td> 182<td align="center"> 183 184![image](https://user-images.githubusercontent.com/26391143/232169642-e2c2e4e4-653c-4d98-8515-31cd41e250c8.png) 185 186</td> 187</tr> 188 189</table> 190 191### Demo Sites 192 193The following DokuWiki sites use the KaTeX plugin: 194 195> **Note** If you're and using KaTeX plugin on your DokuWiki instance, feel free to add it to the list . 196 197## Contribution 198 199This project exists thanks to all the people who contribute: 200 201<a href="https://github.com/Hsins/dokuwiki-plugin-katex/graphs/contributors"> 202 <img src="https://contrib.rocks/image?repo=Hsins/dokuwiki-plugin-katex" /> 203</a> 204 205## License 206 207Licensed under the GPL-3.0 License, Copyright © 2023-present **H.-H. PENG (Hsins)**. 208 209<div align="center"> 210 <sub>Assembled with ❤️ in Taiwan.</sub> 211</div>