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>