DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== MathJax Plugin ======

---- 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 : 2021-05-23
compatible : Hogfather, Greebo, Frusterick Manners, 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/
donationurl: 
----

===== Overview =====

This plugin adds [[http://www.mathjax.org/|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.

It has been tested with MathJax version 2.7.x, the default MathJax version loaded by the plugin is 2.7.x, and all of the links to documentation here point to the v2.7 documentation.  The plugin //does not// work with MathJax v3.x without modifications ([[https://github.com/liffiton/dokuwiki-plugin-mathjax/issues/37|work in progress]]).

===== Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

===== Examples/Usage =====

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):

====Inline Math====

Use dollar signs:

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

or escaped parentheses:

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

====Display Math====

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

$$ \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] \]

A wide range of math environments((Accepted math environments (specified [[https://github.com/liffiton/dokuwiki-plugin-mathjax/blob/master/syntax/protecttex.php#L27|here]] in the code): align, align*, alignat, alignat*, displaymath, eqnarray, eqnarray*, equation, equation*, flalign, flalign*, gather, gather*, math, multline, multline*)) 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*}

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.

===== Configuration and Settings =====

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 loads the script from the [[https://cdnjs.com/libraries/mathjax|CDNJS CDN]].  The default URL loads MathJax securely (via HTTPS).

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.

For more information on configuring MathJax, see [[https://docs.mathjax.org/en/v2.7-latest/config-files.html|Common Configurations]] and [[https://docs.mathjax.org/en/v2.7-latest/options/index.html|MathJax Configuration Options]] in the [[https://docs.mathjax.org/en/v2.7-latest/|MathJax documentation]].

==== Third-Party Extensions ====

Some [[https://docs.mathjax.org/en/v2.7-latest/options/ThirdParty.html|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, set the Dokuwiki configuration option ''plugin»mathjax»url'' to ''%%https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-AMS_HTML.js%%'' (changing it to use the ''Tex-AMS_HTML'' MathJax configuration rather than ''TeX-AMS_CHTML'') to allow XyJax to work.

==== AsciiMath ====

MathJax has the ability to parse and render [[http://asciimath.org/|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 [[http://docs.mathjax.org/en/v2.7-latest/config-files.html|configuration file]]: set ''plugin»mathjax»url'' to ''%%https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=AM_CHTML.js%%''.
==== Automatic Equation Numbering ====

MathJax 2.0 introduces [[https://docs.mathjax.org/en/v2.7-latest/tex.html#automatic-equation-numbering|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 [[http://docs.mathjax.org/en/v2.7-latest/tex.html#automatic-equation-numbering|MathJax documentation]] or the [[https://cdn.rawgit.com/mathjax/MathJax/2.7.7/test/examples.html|MathJax examples page]] for the syntax for creating automatic references to equations, as well.

==== Changing default size or scale ====

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
  }
  });
===== Development =====

{{rss>https://github.com/liffiton/dokuwiki-plugin-mathjax/commits/master.atom date}}

Please see the [[https://github.com/liffiton/dokuwiki-plugin-mathjax|GitHub repository]] for the [[https://github.com/liffiton/dokuwiki-plugin-mathjax/issues|issue tracker]] (to view known issues or report problems) and for a [[https://github.com/liffiton/dokuwiki-plugin-mathjax/commits/master|history of changes]].

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

===== Notes on Older Versions =====

==== Workaround for IE and Old Dokuwiki Versions ====

Dokuwiki versions 2012-01-25 'Angua' and earlier have a bug that prevents this plugin from working when using Internet Explorer.  [[bug>2563|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 ''_tpl_metaheaders_action()'' to:

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

==== CDN Update - March, 2017 ====

Until March 31, 2017, this plugin was using the MathJax CDN for loading MathJax.  MathJax has [[https://www.mathjax.org/cdn-shutting-down/|shut down]] its CDN as of April 30, 2017.

The default URL from which the plugin loads MathJax has been changed to use CDNJS as the MathJax maintainers recommend. If you have not changed the URL in your configuration, just update the plugin to its latest version, and your wiki should start using the new URL automatically. If you **have** modified the URL and are still using the MathJax CDN, you will need to update it in the wiki configuration manager (e.g. following the recommendation in the [[https://www.mathjax.org/cdn-shutting-down/|shutdown notice]]). And if you are not using the MathJax CDN, this should not affect you.

===== FAQ =====

:?: 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.

> Update: Recently, after fixing [[https://github.com/liffiton/dokuwiki-plugin-mathjax/issues/5|this bug]], this code **may** be rendered by Mathjax as well. --- Johan

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:

* [[http://www.dessci.com/en/products/mathtype/|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
  * [[http://www.grindeq.com|GrindEQ]]
  * [[http://www.word2tex.com|Word2tex]]
  * [[http://tug.org/utilities/texconv/pctotex.html|...much more info...]]

----

:?: Is processing of Latex code disabled using [[:wiki:syntax |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 [[:wiki:syntax#code_blocks|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**: [[http://docs.mathjax.org/en/v2.7-latest/tex.html#defining-tex-macros|Yes]], either in your page inside math delimiters or through the configuration script.

----

:?: Will Mathjax work with PDF export plugins like [[plugin:dw2pdf]]?

**Answer**: Unfortunately, no.  Mathjax renders all math formulas on the client-side (in your browser) using Javascript.  The [[plugin: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 [[https://github.com/mathjax/MathJax/issues/447|siunitx.js]])?

**Answer**: Get the [[https://raw.githubusercontent.com/burnpanck/MathJax-third-party-extensions/add-siunitx-tex-extension/siunitx/unpacked/siunitx.js|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 [[https://docs.mathjax.org/en/v2.5-latest/tex.html#tex-macros|mathjax docu]])

----

:?: How to configure the MathJax plugin step by step so that we can use XyJax in DokuWiki?

The section on third-party extensions that mentions XyJax has been updated to correct the URL for the new CDN.  For instructions on installing/using XyJax, there's [[https://github.com/sonoisa/XyJax|the XyJax README]].  It will involve modifying and hosting the XyJax javascript file yourself (it isn't available on a CDN as far as I can tell), which is outside of the scope of this plugin.

(Here are the steps of installation/configuration: a) Change the value of ''plugin>>mathjax>>url'' according to the Section of Third-Party Extensions. b) Follow the five steps of Installation Method 1 at [[https://github.com/sonoisa/XyJax|the XyJax README]]. For details, see https://forum.dokuwiki.org/thread/12374)

----

===== Discussion =====

> If a **search** phrase occurs in a formula, then that formula is not rendered. --- Johan
>> I think this is due to [[bug>2321|this bug]] in core DokuWiki. --- [[user>ach|Anika Henke]] //2012/09/18 11:50//

> Since Dokuwiki version Adora Belle, if the mouse is moved over a rendered formula, that formula is **not** automatically 'enlarged' anymore - that is: as if you move a magnifying glass above it. If I remember correctly, this **was** the case in Angua. --- Johan
>> This is a feature of Mathjax that can be enabled via the configuration string.  It isn't affected by the Dokuwiki version; I've tested it successfully in Angua.  You can enable it temporarily in the right-click context menu for any Mathjax-rendered math, or you can add the following to your Mathjax configuration to make it automatic on all pages: ''menuSettings: { zoom: 'Hover' }''  --- Mark
>>> Tnx. More info: [[http://www.mathjax.org/docs/2.0/options/MathZoom.html]] --- Johan

> **Printing** (via the browser ''File > Print'') yields **overlap** between inline Mathjax content and the normal non-Mathjax text that follows. --- Johan
>> The [[http://docs.mathjax.org/en/v2.7-latest/output.html|Mathjax documentation]] says, "The HTML-CSS output uses web-based fonts so that users don’t have to have math fonts installed on their computers, which introduces some printing issues in certain browsers."  And later, "The SVG output mode is high quality and slightly faster than HTML-CSS, and it does not suffer from some of the font-related issues that HTML-CSS does, so prints well in all browsers."  If you right-click on a math expression, you can change the renderer temporarily for that page to "SVG."  In my browser (FF 18), that will re-render the page such that it prints correctly.  You could change the renderer for all pages to SVG in your wiki's Mathjax configuration, or just do it within a page each time you want to print. --- Mark

> **Spacing** in vertical direction around displayed equations ''$$e = mc^2$$'' are larger than desired if such an equation is preceeded and followed by a blank line. However, removal of blank lines reduces the source readability. What is the best practice? --- Johan
>>This simply does the trick:
  text text text
  $$
  e = mc^2
  $$
  text text text
--- Johan

Please fill all the letters into the box to prove you're human. Q M᠎ G S K Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International