README.md
1<!-- badges -->
2<div align="right">
3
4 [](./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[](https://www.dokuwiki.org/plugin:katex)
18[](./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
180
181</td>
182<td align="center">
183
184
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>
README_zh-TW.md
1<!-- badges -->
2<div align="right">
3
4 [](./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�� _一款用於解析_ $\TeX{}$ _表達式，並使用 [KaTeX](https://katex.org/) 及 [mhchem](https://mhchem.github.io/MathJax-mhchem/) 於頁面中渲染數學／化學方程式的 DokuWiki 外掛。_
16
17[](https://www.dokuwiki.org/plugin:katex)
18[](./CHANGELOG_zh-TW.md)
19
20</div>
21
22## 安裝說明
23
24安裝外掛到您 DokuWiki 站點的方式，大致上有三種：
25
26- **方法一** — 使用 [DokuWiki 外掛管理工具](https://www.dokuwiki.org/plugin:extension) 搜尋並安裝外掛
27- **方法二** — 下載外掛程式並解壓縮到伺服器上的 `<DOKUWIKI_DIR>/lib/plugins/katex` 目錄
28- **方法三** — 透過 [DokuWiki 命令行工具](https://www.dokuwiki.org/plugin:cli) 安裝並維護外掛
29
30使用 DokuWiki 命令行工具的範例如下：
31
32``` bash
33# 透過 Git 安裝 KaTeX 外掛
34$ ./bin/gittool.php clone katex
35
36# 與 clone 命令相同，但當找不到 git 來源時下載檔案安裝
37$ ./bin/gittool.php install katex
38```
39
40## 設定與選項
41
42### 資源託管
43
44您可以選擇將 KaTeX 資源檔案託管於主機上，或是選擇下列其中一個內容交付網路提供商（Content Delivery Network, CDN）：
45
46| 選項 | 說明 |
47| :---------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------- |
48| 自行託管 | 在您自己的 DokuWiki 站點上託管資源檔案，文件將包含於 DokuWiki 的 KaTeX 外掛中。 |
49| [BootCDN](https://www.bootcdn.cn/) | BootCDN 是由 [Bootstrap 中文網](https://www.bootcss.com/) 維護，託管於 [極兔雲](https://www.jitucdn.com/) 的免費 CDN 服務。 |
50| [cdnjs](https://cdnjs.com/) | cdnjs 是有超過 12.5% 以上的網站在使用的開源免費 CDN 服務，由 Cloudflare 提供支援。 |
51| [UNPKG](https://www.unpkg.com/) | UNPKG 在全球提供 npm 倉庫的快速的 CDN 服務，由 Cloudflare 提供支援。 |
52| [jsDelivr](https://www.jsdelivr.com/) | JsDelivr 為開源專案文件提供免費的 CDN 服務；該服務沒有頻寬限制或進階付費功能，任何人都可以完全免費使用。 |
53| [jsHub](https://jshub.com/) | jsHub 是一個開源專案，致力於提供穩定且快速的 CDN 服務，其中收錄的開源專案與 [cdnjs](https://github.com/cdnjs/cdnjs) 專案倉庫保持同步。 |
54| [Staticfile CDN](https://staticfile.org/) | Staticfile CDN 在中國提供穩定且快速的 CDN 服務，由 [七牛雲](http://qiniu.com/) 和 [掘金社區](https://juejin.cn/) 提供技術支援。 |
55
56> **Note** DokuWiki KaTeX 外掛程式中，含有自 KaTeX [發佈頁面](https://github.com/KaTeX/KaTeX/releases) 所下載的最新版本資源檔案。
57
58### 擴充功能
59
60DokuWiki KaTeX 外掛支援了部分由 KaTeX 提供的 [擴充功能](https://katex.org/docs/libs.html)，用以提升使用者體驗或增添額外的功能：
61
62| 設定選項 | 說明 |
63| :------------------: | :----------------------------------------------------------------------------- |
64| `extension-copy-tex` | 啟用後，在選取並複製經 KaTeX 渲染後的元素時，會複製原始的 TeX 表達式到剪貼簿中 |
65| `extension-mhchem` | 啟用後，可以更為容易地撰寫化學方程式 |
66
67您可以在您 DokuWiki 站點的系統設定頁面中，選擇啟用或禁用這些擴充功能。
68
69### 渲染選項
70
71DokuWiki KaTeX 外掛允許您自訂部分 KaTeX 渲染時的 [設定選項](https://katex.org/docs/options.html)：
72
73| 設定選項 | 說明 |
74| :----------------------: | :---------------------------------------------------------------------------------------------------------------------- |
75| `option-output` | 渲染時輸出的標記語言。 |
76| `option-delimiters` | 用於查找表達式的分隔符號列表，依列表相同的順序處理。 |
77| `option-ignored-tags` | 遞迴時要忽略的 DOM 節點標籤列表。 |
78| `option-ignored-classes` | 遞迴時要忽略的 DOM 節點類別名稱列表。 |
79| `option-throwonerror` | 當遇到不支援的命令或無效的 $\LaTeX{}$ 語法時拋出 `ParseError`；否則，KaTeX 會將不支援的語法以指定的錯誤顏色渲染成文字。 |
80| `option-error-color` | 當 `throwonerror` 設置為「否」（未勾選）時，呈現不支援的命令和無效的 $\LaTeX{}$ 語法的顏色。 |
81| `option-macros` | 自定義巨集的集合，每個巨集將命令（command）映射到對應的展開（expansion）。 |
82
83#### 設定選項：`option-output`
84
85- `HTML` 選項只將 KaTeX 表達式輸出為 HTML 標籤。
86- `MathML` 選項只將 KaTeX 表達式輸出為 MathML 標籤。
87- `HTML and MathML` 選項同時將 KaTeX 表達式輸出為 HTML 與 MathML 標籤，前者用於視覺顯示，後者提高訪問性。
88
89#### 設定選項：`option-delimiters`
90
91**範例**
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**說明**
101
102- 每一行只能有一個 delimiter 並且行尾不需要加上逗號。
103- 每一個 delimiter 應該含有三種屬性：
104 - `left`: 內容為 **string** 型別，標示為數學表達式的起始分界符號。
105 - `right`: 內容為 **string** 型別，標示為數學表達式的結束分界符號。
106 - `display`: 內容為 **boolean** 型別，用以表示是否將數學表達式以展示模式（Display Mode）顯示。
107- 每一個 delimiter 應該滿足 [JSON](http://www.json.org/) 格式，其中在表達字串型別時，須以雙引號包圍字串而非使用單引號包圍字串。
108- 順序會影響渲染時的解析順序。
109
110#### 設定選項：`option-ignored-tags`
111
112**範例**
113
114``` plain
115script, noscript, style, textarea, pre, code, option
116```
117
118**說明**
119
120- 以逗號分隔標籤。
121
122#### 設定選項：`option-ignored-classes`
123
124**範例**
125
126``` plain
127code-mirror, annotation-box
128```
129
130**說明**
131
132- 以逗號分隔類別名稱。
133
134#### 設定選項：`option-error-color`
135
136**範例**
137
138``` plain
139#CCDDFF
140#719
141```
142
143**說明**
144
145- 用以表示色彩數值的字串，應以 HEX3（`#XXX`）或 HEX6（`#XXXXXX`）格式表達。
146
147#### 設定選項：`option-macros`
148
149**範例**
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**說明**
160
161- 每一行只能有一個 macro 並且行尾不需要加上逗號。
162- 每一個 macro 應該含有兩種屬性：
163 - `command`: 內容為 **string** 型別，標示為映射巨集展開時的名稱。
164 - `expansion`: 內容為 **string** 型別，用以表示對應的巨集展開內容。
165- 每一個 macro 應該滿足 [JSON](http://www.json.org/) 格式，其中在表達字串型別時，須以雙引號包圍字串而非使用單引號包圍字串。
166
167## 截圖與演示
168
169### 螢幕截圖
170
171<table>
172<tr>
173 <th> 頁面渲染 </th>
174 <th> 外掛設定 </th>
175</tr>
176<tr>
177<td align="center">
178
179
180
181</td>
182<td align="center">
183
184
185
186</td>
187</tr>
188
189</table>
190
191### 演示站點
192
193以下這些 DokuWiki 站點都使用了 KaTeX 外掛：
194
195> **Note** 如果您在自己的 DokuWiki 站點上使用了 KaTeX 外掛，歡迎將您的站點添加到上述列表 ��。
196
197## 貢獻須知
198
199本專案感謝以下開發人員的貢獻：
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## 授權許可
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>
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
