====== KaTeX Plugin ====== ---- plugin ---- description: Parsing TeX expressions and rendering them into math/chemical equations with KaTeX and mhchem author : H.-H. PENG (Hsins) email : hsinspeng@gmail.com type : syntax, action lastupdate : 2023-04-15 compatible : Jack Jackrum depends : conflicts : similar : jsmath, latex, mathjax tags : chemical, equation, tex, latex, math, physics downloadurl: https://github.com/Hsins/dokuwiki-plugin-katex/zipball/main bugtracker : https://github.com/Hsins/dokuwiki-plugin-katex/issues sourcerepo : https://github.com/Hsins/dokuwiki-plugin-katex/ donationurl: screenshot_img : https://user-images.githubusercontent.com/26391143/232326256-dd5c8691-3d02-4835-96ff-2f2b1820a289.png ---- [[https://github.com/Hsins/dokuwiki-plugin-katex/blob/main/LICENSE|{{ https://img.shields.io/github/license/Hsins/dokuwiki-plugin-katex.svg?label=License&style=flat-square}}]] ===== Overview ===== {{ https://user-images.githubusercontent.com/26391143/232326068-ec1fda94-89a1-4de3-b092-98e360869bad.png?nolink&256 }} 🧩 The **KaTeX Plugin** is a DokuWiki plugin for parsing TeX expressions and rendering them into math/chemical equations with [[https://katex.org/ | KaTeX]] and [[https://mhchem.github.io/MathJax-mhchem/ | 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 [[plugin:extension|Extension Manager]]. * __**Method 02**__ β€” Download the extension and unpack it into ''/lib/plugins/katex'' on your server. * __**Method 03**__ β€” Maintain and install with [[cli|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 [[https://www.overleaf.com/learn/latex/Display_style_in_math_mode|Overleaf Documentation]]: {{ https://user-images.githubusercontent.com/26391143/232506985-2bae3cf3-7753-4287-8fbf-149f11c3134a.png?nolink }} 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 [[#configurationdelimiters|configuration of the delimiters]]: * **Inline Mode** use the syntax like ''$$'' or ''\(\)$''. * **Display Mode** use the syntax like ''$$$$'' or ''\[\]''. Besides, delimiters with space or newline are available: {{https://user-images.githubusercontent.com/26391143/232520964-bbac1e19-c724-456c-ba0c-26996d80a4fc.png?300 }} **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'' [[#extensions|extension]] must be enabled. {{https://user-images.githubusercontent.com/26391143/232523255-e0719164-4bc3-40f1-b3f5-e9ef3f341c3c.png?300 }} **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 [[https://mhchem.github.io/MathJax-mhchem/|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. | | [[https://www.bootcdn.cn/|BootCDN]] | BootCDN is the free CDN service maintained by [[https://www.bootcss.com/|Bootstrap China]] and hosted by [[https://www.jitucdn.com/|Jitu Cloud]]. | | [[https://cdnjs.com/|cdnjs]] | cdnjs is a free and open-source CDN service trusted and used by over 12.5% of all websites, powered by Cloudflare. | | [[https://www.unpkg.com/|UNPKG]] | UNPKG is a fast, global CDN service for everything on npm, powered by Cloudflare. | | [[https://www.jsdelivr.com/|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. | | [[https://jshub.com/|jsHub]] | jsHub is an open source project dedicated to for providing stable, fast and free CDN service. The packages are mainly synchronized with the [[https://github.com/cdnjs/cdnjs|cdnjs]] repository. | | [[https://staticfile.org/|Staticfile CDN]] | Staticfile CDN provide stable and fast CDN service in China. Powered by [[http://qiniu.com/|Quniu Cloud]] and supported by [[https://juejin.cn/|Juejin Community]] | > __**Note**__ > The KaTeX plugin for DokuWiki will contain the latest version of KaTeX from its [[https://github.com/KaTeX/KaTeX/releases|release page]]. ==== Extensions ==== The KaTeX plugin for DokuWiki supports some of the [[https://katex.org/docs/libs.html|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 [[https://katex.org/docs/options.html|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 [[http://www.json.org/|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 [[http://www.json.org/|JSON]] format, and double quotes should be used instead of single quotes when representing strings. ===== Sreenshots and Demo Sites ===== ==== Screenshots ==== ^ Rendering\\ ([[~pagesource-screenshots|pagesource]]) ^ Configuration ^ | {{https://user-images.githubusercontent.com/26391143/232169170-80e367da-a854-473e-a017-1dc50b5ea1d8.png?325}} | {{https://user-images.githubusercontent.com/26391143/232169642-e2c2e4e4-653c-4d98-8515-31cd41e250c8.png?325}} | ==== 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)**.