From Wikipedia, the free encyclopedia
Jump to: navigation, search
This script is no longer maintained, as Nageh has retired; please disregard any instructions in the template below to contact him.
No official MathJax preference is currently available.

mathJax is a port and frontend of MathJax for use on Wikipedia. It was created out of dissatisfaction with the current state of maths formatting:

  • Aliased PNG bitmap graphics.
  • Too large font for inline maths with people using hacks like \scriptstyle in consequence.
  • Wrong baseline for inline maths.
  • No scaling of graphics with user-configured font sizes.
  • Little control over when HTML over PNG rendering is selected by the backend depending on the selected user preferences for math display (six different settings!).
  • Wrongly implemented symbols in the texvc rendering backend.
  • And finally, inconsistencies due to some people preferring HTML over TeX and vice versa.

This user script is being taken as the basis to implement global MathJax support in the MediaWiki software.

Differences to the global MediaWiki option[edit]

The mathJax user script has been taken as the basis to implement global MathJax support in the MediaWiki software, and is now available as an experimental feature in your preferences menu. The difference between the MediaWiki option and the user script is that the latter is generally more up to date but also somewhat more experimental. Also, bug reports for the user script are taken care of at this page whereas bug reports for the MediaWiki option must be submitted via Bugzilla.

Quick test setup of MathJax in Wikipedia[edit]

If you quickly want to test MathJax in Wikipedia, just follow these two simple steps.

Step 1. Add the following two lines to your common script file:

mathJax={}; mathJax.fontDir="";

If you are using Wikipedia's secure server, you should instead add:

mathJax={}; mathJax.fontDir="";

Step 2. Go to Preferences->Appearance and change the Math setting to "Leave it as TeX (for text browsers)".

Wikipedia should now be configured to use MathJax.

Note. If you want to keep using MathJax, it is highly recommended to install the fonts on your local machine as described in the detailed installation instructions below.

Current state[edit]

mathJax is in a testing phase. This means that it is not ready for full deployment, but you are welcome to try it and give feedback. A next step will be taken once it has been determined that MathJax has become fast enough to satisfy most users, and no other obvious issues are left. This may result either in extending this user space extension, possibly with webfonts uploaded on some Wikimedia server, or in the installment of an official MediaWiki extension.

Update: MathJax has been upgraded to version 1.1. Frontend has been updated as well, and is now compatible with wikEd and ajaxPreview. Further changes: MathJax gets only loaded on pages with maths elements, combined scripts for faster startup, inline maths starting with \scriptstyle (a common hack) gets automatically turned into \textstyle for equal font size with surrounding text.

2. Update: Webfonts are now supported via the MathJax CDN. Fix: change fontdir to fontDir in vector.js (capitalization)

Intermediate Update: (Official) support for customization, support for color commands, update to MathJax v1.1a.

3. Update: mathJax has just been upgraded to the recently released version 2.0 of MathJax. As always, post any bug reports on the talk page, and don't forget to clear your cache!

Minor update: Support for overriding the default font (thanks to dpvc from the MathJax crew).
Minor update 2: Support for STIX fonts in the HTML-CSS rendering mode. These fonts will now be selected by default when available locally.
Update 3: Better implementation of \oiint and \oiiint, support for \textsf, \texttt and \vline commands, and support for the RGB color space model (so \definecolor does not fail anymore). noErrors.js extension has been removed – no idea why I had included it in the first place as it avoids displaying a specific error message when a maths expression is erroneous.

Maintenance update: MathJax has been updated to version 2.1.

Installation instructions[edit]

For normal users:

  1. Configure fonts:
    • Either: Download the MathJax package from here, and install the 22 .otf files in fonts/HTML-CSS/TeX/otf/ into your system font directory for best performance, or if you wish to continue using the extension.
    • Or: Add the following line to your common script file (or to your custom skin file) in order to use webfonts:
      mathJax={}; mathJax.fontDir="";
      (If you are using Wikipedia's secure server, add: mathJax={}; mathJax.fontDir=""; )
  2. Add the line importScript('User:Nageh/mathJax.js'); to your skin file (right after the webfonts line).
  3. Set the Appearance to "Leave it as TeX" in your Preferences.

Or, if your browser supports MathML (currently only Firefox acceptably implements MathML, and you have to install STIX fonts to optimize look&feel)

  1. Add the line importScript('User:Nageh/mathJax.js'); to your skin file (right after the webfonts line).
  2. Set the Appearance to "Leave it as TeX" in your Preferences.
  3. Go to an article with math, right click on the formula and choose Settings→Math Renderer→MathML.

Note: Webfonts are hosted on the MathJax CDN servers, which are not intended to deal with high volumes of traffic. If you intend to use the extension for more than some testing please consider installing local fonts; for installation details of the STIX fonts see this page. (In the long term, we need to host the files on our own servers.)

Font issues[edit]

The quality of font rendering is dependent on your browser and operating system. In general, speed and appearance can be improved by installing the STIX fonts (see the MathJax font help page). The Chrome browser is affected by a web font rendering bug since version 18 that may result in your formulas looking overly bold and jagged. This can be overcome by locally installing fonts.

Usage notes[edit]

mathJax implements a heuristic to automatically tell apart display maths from inline maths: most of the time it will correctly determine whether some maths should be rendered with big operators or with small ones. Being a heuristic it may fail: in this case you can force mathJax to render in a particular mode by preceding your TeX code with \displaystyle or \textstyle .

mathJax also detects the \scriptstyle hack that is commonly used with Wikipedia's default texvc PNG rendering to enforce a font size that approximately matches that of the surrounding text. mathJax will replace any occurence of \scriptstyle (with or without whitespace at the front) that it finds at the beginning of TeX code with \textstyle to effect a normal inline maths rendering. In the unusual case that you really want some formula to be rendered in a script-style font size you must enclose your entire TeX formula in curly braces.


MathJax can be customized by defining the mathJax.userConfig structure, which is formatted according to the documentation here. For example, adding the following line to your skin file right before you load the extension will redefine the TeX command \tfrac to be always rendered as \dfrac:

mathJax={}; mathJax.userConfig = { TeX: { Macros : {tfrac : ["\\dfrac{#1}{#2}",2] }}};

If you want you can also override the default font. For example, if you prefer a sans-serif font variant to the serif style, add the following line to your skin file right before you import the mathJax script:

mathJax={}; mathJax.fontVariant = "MathJax_SansSerif";

Note that the sans-serif MathJax font has a slightly more bold face than the serif variant. Note also that changing the default font style does only work for the HTML-CSS renderer.


To see which version of mathJax and MathJax you are using, enter either javascript:alert(mathJax.version) or javascript:alert(MathJax.version) into your browser address bar.

External links[edit]