—- plugin —- description: Enables MathJax [http://mathjax.org] parsing of TeX math expressions in wiki pages author : Mark Liffiton email : liffiton@gmail.com type : action, syntax lastupdate : 2016-03-28 compatible : Ponder Stibbons, Rincewind, Angua, Adora Belle, Weatherwax, Binky, 2014-09-29 “Hrun”, Detritus, Elenor of Tsort depends : conflicts : creole, indexmenu2, revealjs, s5 similar : jsmath, latex tags : math,tex,latex,mathjax

downloadurl: https://github.com/liffiton/dokuwiki-plugin-mathjax/archive/master.zip bugtracker : https://github.com/liffiton/dokuwiki-plugin-mathjax/issues sourcerepo : https://github.com/liffiton/dokuwiki-plugin-mathjax/

This plugin adds MathJax to your wiki pages to let you easily write mathematical formulas that will be typeset and displayed cleanly. It is written to be as simple as possible; it loads and configures the script, protects TeX math expressions from other parsing, and no more.

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Dokuwiki versions 2012-01-25 'Angua' and earlier have a bug that prevents this plugin from working when using Internet Explorer. The bug has been fixed and shouldn't be a problem in later releases, but 2012-01-25 and before need the following workaround applied for math to render in IE:

Edit inc/template.php and change lines 375-377 (assuming the 2012-01-25 “Angua” release) in tplmetaheaders_action() to:

$attr['_data'] = "/*<![CDATA[*/\n".
    $attr['_data'].
    "\n/*!]]>*/";

NOTE that the default configuration uses $ (dollar signs) to delimit TeX formulas. This may cause trouble if you have $ characters in any pages. The default configuration also lets you escape the dollar signs, however, by changing them to '\$'. This should correct any problems you might have.

Once the plugin is installed, you can write TeX formulas in your wiki with the following syntax (by default — all delimiters are configurable):

Use dollar signs:

$a^2 + b^2 = c^2$

$a^2 + b^2 = c^2$

or escaped parentheses:

\(1+2+\dots+n=\frac{n(n+1)}{2}\)  

(1+2+\dots+n=\frac{n(n+1)}{2})

To display math on its own line, use double dollar signs:

$$ \frac{d}{dx}\left( \int_{0}^{x} f(u)\,du\right)=f(x) $$

$$ \frac{d}{dx}\left( \int_{0}^{x} f(u)\,du\right)=f(x) $$

or escaped square brackets:

\[ \sin A \cos B = \frac{1}{2}\left[ \sin(A-B)+\sin(A+B) \right] \]

[ \sin A \cos B = \frac{1}{2}\left[ \sin(A-B)+\sin(A+B) \right] ]

A wide range of math environments¹⁾ will work as well:

\begin{align*}
e^x & = 1 + x + \frac{x^2}{2} + \frac{x^3}{6} + \cdots \\
    & = \sum_{n\geq 0} \frac{x^n}{n!}
\end{align*}

\begin{align*} e^x & = 1 + x + \frac{x^2}{2} + \frac{x^3}{6} + \cdots \\ & = \sum_{n\geq 0} \frac{x^n}{n!} \end{align*}

Note that the math environments should not be inside the dollar sign delimiters; the environments should stand on their own with just the \begin and \end statements in order to be parsed correctly.

The plugin installs with a default configuration that should work for most users. It is ready to go upon installation, and extra configuration is only required for specific needs.

The URL to the MathJax script can be set in the Configuration Manager. By default, it uses the MathJax CDN, loading the latest version of MathJax from a remote server maintained and updated by the MathJax team. The default URL loads MathJax securely (via HTTPS) if the wiki itself is served securely.

You can host your own installation of MathJax instead, in which case you can change the URL to point to your own installation, either as a complete URL or as an absolute path to the MathJax directory on your server (from the web root, e.g., “/scripts/mathjax.js” for “http://your.site/scripts/mathjax.js”).

Additionally, you can configure MathJax via commands given in a configuration string and/or loaded from files; both methods can be controlled in the Configuration Manager. Note that the default URL loads a reasonable configuration from the CDN, and the default configuration string modifies it slightly.

Some third-party MathJax extensions may require a different configuration than the plugin's default to operate properly. For example, it has been reported that the XyJax extension does not function with the “CHTML” renderer. In that case, changing the MathJax URL to //cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML (changing the 'config' parameter from the default) allows XyJax to work.

For more information on configuring MathJax, see Common Configurations and MathJax Configuration Options in the MathJax documentation.

MathJax has the ability to parse and render AsciiMath markup, but it is not enabled in the default configuration of this plugin. One easy way to enable the AsciiMath preprocessor is to use a different configuration file: set plugin»mathjax»url to //cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML. (That configuration enables both TeX and AsciiMath; see the list of configuration files for other options.) You may want to modify some AsciiMath-specific settings as well.

MathJax 2.0 introduces automatic equation numbering, but it is not enabled in the default configuration. To enable it, go to your wiki's configuration editor and change the plugin»mathjax»config setting to something like this:

MathJax.Hub.Config({
  tex2jax: {
    inlineMath: [ ["$","$"], ["\\(","\\)"] ],
    displayMath: [ ["$$","$$"], ["\\[","\\]"] ],
    processEscapes: true
  },
  TeX: { equationNumbers: {autoNumber: "AMS"} }
});

The line TeX: { equationNumbers: {autoNumber: “AMS”} } enables the equation numbering.

See the MathJax documentation or the MathJax examples page for the syntax for creating automatic references to equations, as well.

The default size of equations can be changed by adding the “CommonHTML” section and using the “scale” parameter. A value of “125” means “125%”.

MathJax.Hub.Config({
  tex2jax: {
      inlineMath: [ ["$","$"], ["\\(","\\)"] ],
      displayMath: [ ["$$","$$"], ["\\[","\\]"] ],
      processEscapes: true
  },
CommonHTML: {
  scale: 125
}
});

• Put asciimath support behind a config flag to avoid conflict with mar… (2021/11/21 )
• Remove string substitutions that break mhchem formulas. Fixes #39. (2021/05/24 )
• Update plugin info. (2020/12/15 )
• Bump to latest 2.x version. (2020/12/15 )
• Protect AsciiMath default backtick delimiters from Dokuwiki parsing, … (2020/12/15 )
• Mathjax version bump; update doc URLs to https. (2018/06/24 )
• Bump date in plugin info. (2018/04/28 )
• Cleanup render() (oops on those non-breaking spaces) and make it alwa… (2018/04/28 )

Please see the GitHub repository for the issue tracker (to view known issues or report problems) and for a history of changes.

Alternatively, feel free to report issues in the Discussion section below.

What happens if the Latex plug-in is installed simultaneously?

Answer: I'm not certain (I don't have a place to easily install both), but if both are setup to use the same syntax for specifying math/equations, in the best case, the Latex plugin will capture/translate them and Mathjax won't see them. I wouldn't recommend trying it, though, as it will most likely just break things. Feel free to update this if you try it and find out what happens.

Update: It seems to work fine. Assume settings for both plug-ins to be default. Result:

'Inline' Latex code like
$a^2 + b^2 = c^2$ is processed by the Mathjax plugin.

'Display math mode' Latex code like

\begin{equation}
a^2 + b^2 = c^2
\end{equation}

is processed (rendered as image) by the Latex plugin.

Tested with browsers: IE 8 and Firefox 13; PHP: QuickPHP 1.14.0; Dokuwiki: Angua

Can (large quantities of) equations be transferred from MS Word to the Wiki?

Answer: Yes, using converters like:

• Mathtype
  • Update: Do not expect too much from Mathtype. In Word 2007, simple symbols like the dot product or a hat (^) will abort the conversion to Latex. For automated batch conversion of even slightly complex math, you're screwed — Johan
• GrindEQ
• Word2tex
• ...much more info...

Is processing of Latex code disabled using syntax like

%%$a^2 + b^2 = c^2$%%

or

<nowiki>$a^2 + b^2 = c^2$</nowiki>?

Answer: No, Mathjax still renders the Latex code as if it is not wrapped by that syntax.

How can I show the original Latex code without any formatting?

Answer: Wrap the Latex code in code blocks, format it with the monospace style (e.g., ''$a^2$''), or escape dollar signs with backslashes (e.g., \$a^2\$).

What happens if the MathJax CDN server goes down?

Answer: Then Mathjax won't load, and the latex source code is shown instead of nicely rendered formulas.

Are \newcommand and other custom macro/environment definitions supported?

Answer: Yes, either in your page inside math delimiters or through the configuration script.

Will Mathjax work with PDF export plugins like dw2pdf?

Answer: Unfortunately, no. Mathjax renders all math formulas on the client-side (in your browser) using Javascript. The dw2pdf plugin creates PDFs on the server-side, where Javascript, and thus Mathjax, is unavailable. So any server-side export like that will contain the raw Latex code, not the rendered math formulas.

You can however export a PDF with the rendered math formulas from your browser by “printing to PDF.” This functionality is built in on OS X and Linux (look for “file” and “PDF” options in your print dialog), and you can add third-party “PDF printer” software to Windows.

How to use (experimental) Extensions to MathJax (like siunitx.js)?

Answer: Get the script file, copy it to [home]/conf/ and then add the path to the file in the config manager (plugin»mathjax»configfile) like: conf/siunitx.js

How to define global shortcuts / new commands?

Answer Add data/pages/mathjax.txt in the configuration manager under plugin»mathjax»configfile and then create the page mathjax with something simmilar to:

MathJax.Hub.Config({
  TeX: {
    Macros: {
      RR: "{\\bf R}",
      bold: ["{\\bf #1}",1],
      Msun: "{\\textrm{M}_{\\odot}}"
    }
  }
});

(taken from the mathjax docu)