Extension:MathJax

From MediaWiki.org
Jump to: navigation, search
The "MathJax display engine" is used experimentally on Wikimedia wikis BUT in combination with the Math extension and not with the MathJax extension documented on this page! If you want to give the "MathJax display engine" on the Wikimedia sites a try you can set this up in your preferences.
MediaWiki extensions manual - list
Crystal Clear action run.png
MathJax

Release status: beta

Implementation Extended syntax
Description Allows math rendering for TeX/LaTeX with the Javascript library MathJax, including LaTeX style formula references.
Author(s) Dirk Nuyens (Dirk Nuyenstalk)
Latest version 0.7 (2013-04-22)
MediaWiki 1.18+
Database changes No
License GPLv3
Download See external source
Hooks used
ParserBeforeInternalParse

InternalParseBeforeLinks
BeforePageDisplay
ParserFirstCallInit

Translate the MathJax extension if possible

Check usage and version matrix; code metrics


The MathJax extension enables MathJax (http://www.mathjax.org/), a Javascript library, for typesetting TeX and LaTeX formulae in MediaWiki inside math environments. The following math environments are defined for inline style math:

  • $...$ (can be turned off, even per page),
  • \(...\) and
  • <math>...</math>.

And the following math environments are defined for display style math:

  • $$...$$ (can be turned off, even per page),
  • \[...\],
  • \begin{...}...\end{...} and
  • :<math>...</math>.

MathJax produces nice and scalable mathematics, see their website (http://www.mathjax.org/) for a demonstration. This extension also enables the usage of \label{} and \eqref{} tags with automatic formula numbering. If needed you can still hand label by using \tag{}.

Installation[edit | edit source]

  • Download and extract the files in a directory called MathJax in your extensions/ folder. If you're a developer and this extension is in a Git repository, then instead you should clone the repository.
  • Add the following code at the bottom of your LocalSettings.php:
require_once( "$IP/extensions/MathJax/MathJax.php" );
/** There is a bug in Extension:MathJax with MediaWiki 1.19.0, 1.20.0 and 1.21.1
*   If you are using any form of PHP caching on your wiki and you have setup
*   your wiki to use variable caching like $wgMainCacheType = CACHE_ACCEL; 
*   you could encounter issues with rendering of formulas. 
*   If so uncomment the last line.
*/
#$wgParserCacheType = CACHE_NONE;
  • Done! Navigate to "Special:Version" on your wiki to verify that the extension is successfully installed.

It doesn't matter if you have $wgUseTeX set to true or false. Extension:MathJax will take over rendering of the standard <math> rendering.

Configuration[edit | edit source]

Note: By default the extension is configured to use the MathJax CDN. The following are optional and must be placed after the require_once:

  • MathJax_Parser::$MathJaxJS: Location of the public javascript entry-point. By default this points to the MathJax CDN. If you don't want to rely on a third party, or can't share traffic information with a third party, you could install it locally: read the documentation in MathJax.php
  • MathJax_Parser::$MathJaxConfig: The MathJax configuration file to use, defaults to mwMathJaxConfig.js that comes with the extension. This is a file you need to download and save as well.
  • MathJax_Parser::$disabled: Disable the extension unless marked on the page to enable it by putting __MATHJAX__ somewhere. You can disable by using __NOMATHJAX__ on a wiki page.
  • MathJax_Parser::$do_number: Turn on or off numbering and \eqref linking by this extension, also by __MATHJAX_NUMBER__ and __MATHJAX_NONUMBER__.
  • MathJax_Parser::$do_dollar: Turn on or off processing of inline math delimited by dollar sign: $...$. Also by __MATHJAX_DOLLAR__ and __MATHJAX_NODOLLAR__.
  • MathJax_Parser::$do_dollardollar: Turn on or off processing of display math delimited by double dollar sign: $$...$$. Also by __MATHJAX_DOLLARDOLLAR__ and __MATHJAX_NODOLLARDOLLAR__.

Easy configuration (using the MathJax CDN)[edit | edit source]

This is the default

By default the MathJax library will be loaded from the MathJax CDN, so you do not have to install the MathJax library (not to confuse with the MathJax MediaWiki extension) yourself.

MathJax also provides a CDN over HTTPS, see http://www.mathjax.org/docs/2.0/start.html#secure-access-to-the-cdn for the current URL. To use it set MathJax_Parser::$MathJaxJS to the provided url in LocalSettings.

Installing locally[edit | edit source]

  1. Acquire the MathJax files as described here in the section 'Downloads for Local Installation'. In this example, we'll assume you placed it in /mathjax. Go to http://example.org/mathjax/test in your web browser to see that the installation works.
  2. Add this configuration after the require_once line in your LocalSettings file:
MathJax_Parser::$MathJaxJS = '/mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML';

Usage[edit | edit source]

This extension allows for typical LaTeX math integration. For example:

<!-- some LaTeX macros we want to use: -->
$
  \newcommand{\Re}{\mathrm{Re}\,}
  \newcommand{\pFq}[5]{{}_{#1}\mathrm{F}_{#2} \left( \genfrac{}{}{0pt}{}{#3}{#4} \bigg| {#5} \right)}
$
 
We consider, for various values of $s$, the $n$-dimensional integral
\begin{align}
  \label{def:Wns}
  W_n (s)
  &:= 
  \int_{[0, 1]^n} 
    \left| \sum_{k = 1}^n \mathrm{e}^{2 \pi \mathrm{i} \, x_k} \right|^s \mathrm{d}\boldsymbol{x}
\end{align}
which occurs in the theory of uniform random walk integrals in the plane, 
where at each step a unit-step is taken in a random direction.  As such, 
the integral \eqref{def:Wns} expresses the $s$-th moment of the distance 
to the origin after $n$ steps.
 
By experimentation and some sketchy arguments we quickly conjectured and 
strongly believed that, for $k$ a nonnegative integer
\begin{align}
  \label{eq:W3k}
  W_3(k) &= \Re \, \pFq32{\frac12, -\frac k2, -\frac k2}{1, 1}{4}.
\end{align}
Appropriately defined, \eqref{eq:W3k} also holds for negative odd integers. 
The reason for \eqref{eq:W3k} was  long a mystery, but it will be explained 
at the end of the paper.

(Which comes from a preprint of Jon M. Borwein, et. al. Some arithmetic properties of short random walk integrals.)

This renders as http://www.cs.kuleuven.be/~dirkn/Extension_MathJax/MathJaxExample.png.

MathJax 2.0[edit | edit source]

The extension has been updated for MediaWiki 1.18.2 and MathJax 2.0 and has undergone a complete rewrite. Changes include:

  • Per page control of options (e.g., turn on or off parsing of $...$).
  • New <nomathjax>...</nomathjax> tag to exclude certain parts from MathJax.
  • Consistent numbering among different formula environments.
  • Numbering can be turned on and off.
  • Use of content delivery network for MathJax, this means you don't have to install MathJax yourself.
  • Zero configuration for default use (except including MathJax in your configuration).

Difference with the default texvc+latex math handling[edit | edit source]

Note: The default Extension:Math now also includes experimental support for MathJax but only through the <math>...</math> tags.

In standard mode math handling on mediawiki is done using texvc from Extension:Math. But, if you

  • don't want to use texvc because you
    • want scalable nicer mathematics,
    • the comfort of a real LaTeX like environment,
    • find having LaTeX on your server too inconvenient (or a security risk); or
  • can't use texvc
    • as you have trouble configuring and compiling, or
    • can't easily write png files (because of safe_mode) or
    • for some other reason,

but still want to render math, then this extension could be a solution for you.

The main reason to use this extension is to have a natural way to write mathematics on your wiki without having to type <math>x</math> when you can just type $x$.

Note that you could as well load the MathJax JavaScript library by customizing your WM skin or account, but there is still one major advantage of this extension over such a method:

  • this extension allows you to use as much white space in your formula as you want.

E.g., writing

$$
  \sum f(x) = F(x) + g(x)
$$

does what you want it to do using this extension, but not when using a customization method as the whitespace at the beginning of line 2 will make WM introduce a <pre> tag and thus break the formula environment for MathJax.

Known issues[edit | edit source]

  • The following will render incorrectly $a<b\&d>c$ as Sanitizer::removeHTMLtags is executed in between the ParserBeforeInternalParse and InternalParseBeforeLinks hooks. A solution is to add a space as in $a<b \& d>c$.
  • This anonymous comment was placed here: "Our wiki had a page the had a dollar sign "$" in it. When we installed MathJax the page refused to load. I suspect that we need one of the parser functions in localsettings, but that should be clearly laid out in the install instructions. Please put comments and queries on the Discussion page of this extension and be more specific." There is not enough information in this message to guess at what the problem is. My guess is that you either installed the extension with an older version of MediaWiki or with an older version of PHP installed. Please enable the extension once more and then check both the php error log and the webserver error log to see what is going on.
  • The work of this extension may interfere with the expansion MagnetLinks

Change log[edit | edit source]

0.5 (20101116)
Initial public release.
0.5.1 (20101201)
Modifications to allow integration with Extension:Semantic_MediaWiki.
Compatability code for Parser::MARKER_SUFFIX added.
0.5.2 (20110203)
Kind of revert move away from the markers used by MW as it does no really matter which ones we use (so no need for the SMW fix from 0.5.1 anymore).
Allowed \label and \tag at the same time as one would expect.
Added clickable links for the formula references, this currently assumes the used label or tag is a valid XHTML id.
0.5.2b (20110215)
Removed redundant comma's in the MathJax configuration hub file to please IE...
0.6 (20120418)
Updates for MediaWiki 1.18 (tested with 1.18.2) and MathJax 2.0, amonst others incorporating a patch from EvanChou (thanks!) and the CDN modification of Evan. This is mainly a maintenance update to get the extension back on track for 1.18.2.
0.7 (20120422)
Complete rewrite, $ and $$ can now be turned on and off, much better protection and detection, numbering is consistent among different environments, no global variables anymore (everything is now in one class), new tag <nomathjax>, magic words to turn on and off features: __MATHJAX__ and __NOMATHJAX__, __MATHJAX_NUMBER__ and __MATHJAX_NONUMBER__, __MATHJAX_DOLLAR__ and __MATHJAX_NODOLLAR__, and __MATHJAX_DOLLARDOLLAR__ and __MATHJAX_NODOLLARDOLLAR__.

See also[edit | edit source]

Language: English  • русский