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}