Skip to content

Latest commit

 

History

History
211 lines (141 loc) · 9.95 KB

README.md

File metadata and controls

211 lines (141 loc) · 9.95 KB
Raw

DokuWiki Plugin: KaTeX

DokuWiki Plugin: KaTeX

🧩 DokuWiki plugin for parsing $\TeX{}$ expressions and rendering them into math/chemical equations with KaTeX and mhchem.

Plugin Page

Installation

There're roughly different 3 methods to install an extension on your DokuWiki instance:

  • Method 01 — Search and install the plugin using the Extension Manager.
  • Method 02 — Download the extension and unpack it into <DOKUWIKI_DIR>/lib/plugins/katex on your server.
  • Method 03 — Maintain and install with 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

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.
BootCDN BootCDN is the free CDN service maintained by Bootstrap China and hosted by Jitu Cloud.
cdnjs cdnjs is a free and open-source CDN service trusted and used by over 12.5% of all websites, powered by Cloudflare.
UNPKG UNPKG is a fast, global CDN service for everything on npm, powered by Cloudflare.
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.
jsHub jsHub is an open source project dedicated to for providing stable, fast and free CDN service. The packages are mainly synchronized with the cdnjs repository.
Staticfile CDN Staticfile CDN provide stable and fast CDN service in China. Powered by Quniu Cloud and supported by Juejin Community.

Note The KaTeX plugin for DokuWiki contain the latest version of KaTeX from its release page.

Extensions

The KaTeX plugin for DokuWiki supports some of the extensions provided by KaTeX for improving user experiences and additional functions:

Configuration Explanation
extension-copy-tex If enabled, when selecting and copying KaTeX-rendered elements, copies their TeX expressions to the clipboard.
extension-mhchem If enabled, you can 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 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: option-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: option-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 JSON format, and double quotes should be used instead of single quotes when representing strings.
  • The order of line matters.

Configuration: option-ignored-tags

Example

script, noscript, style, textarea, pre, code, option

Explanation

  • Each tag should be separated with comma in one line.

Configuration: option-ignored-classes

Exmaple

code-mirror, annotation-box

Explanation

  • Each class should be separated with comma in one line.

Configuration: option-error-color

Example

#CCDDFF
#719

Explanation

  • The color string should be given in HEX3 (#XXX) or HEX6 (#XXXXXX) format.

Configuration: option-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 JSON format, and double quotes should be used instead of single quotes when representing strings.

Sreenshots and Demo Sites

Screenshots

Rendering Configuration

image

image

Demo Sites

The following DokuWiki sites use the KaTeX plugin:

Note If you're and using KaTeX plugin on your DokuWiki instance, feel free to add it to the list 😊.

Contribution

This project exists thanks to all the people who contribute:

License

Licensed under the GPL-3.0 License, Copyright © 2023-present H.-H. PENG (Hsins).

Assembled with ❤️ in Taiwan.