By MW in mediawiki — 31 Jan 2025

Enhancing MediaWiki with MathJax for Mathematical Content

Why bother with MathJax on a MediaWiki?

Ever opened a scientific wiki and found the equations looking like a jumble of back‑slashes and curly braces? It happens more often than you’d think. Readers stumble over raw LaTeX, editors scratch their heads, and the whole page feels half‑finished. MathJax steps in like a backstage crew, turning the cryptic source into clean, scalable, and accessible mathematics, right in the browser.

But MediaWiki already ships a Math extension. So, why add another layer? Short answer: flexibility. Long answer: MathJax supports modern TeX, MathML, and even ASCIIMath; it renders instantly, works offline, and plays nice with mobile devices. In short, it lets you keep the wiki “wiki‑ish” while offering the typographic polish of a research paper.

Choosing the right extension

Two main options exist:

Extension:Math – native to MediaWiki, renders via either PNG images or MathML, depending on the server setup.
Extension:MathJax – a thin wrapper that loads the MathJax JavaScript library and lets the client do the heavy lifting.

If you care about server load, MathJax is the lighter choice. If you need server‑side PDF export, the old Math extension might still have a niche. Most contemporary wikis aiming for a modern feel pick MathJax, and the community has built a decent installation guide around it.

Getting MathJax onto your wiki

First things first – you need a working MediaWiki install. The steps below assume you have shell access and can edit LocalSettings.php. No magic, just a few commands and a pinch of patience.

Step 1: Grab the extension

cd /path/to/your/wiki/extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/MathJax.git

That pulls the latest code. If you prefer a stable release, download the tarball from the extension page and extract it into the extensions directory.

Step 2: Add the loader to `LocalSettings.php`

Open the file at the root of your wiki. Near the bottom, after the other wfLoadExtension calls, drop this line:

wfLoadExtension( 'MathJax' );

That tells MediaWiki to include the extension during bootstrap. It’s as simple as that, but a tiny typo can break the whole site – trust me, I’ve spent a night chasing a missing semicolon.

Step 3: Tell MediaWiki to use MathJax

By default MediaWiki sticks with its own math renderer. Switch it over with a couple of variables:

# Use MathJax for displaying maths
$wgDefaultUserOptions['math'] = 'mathjax';
$wgDefaultUserOptions['math-editor'] = 'simple';

# Optional: load MathJax from a CDN (faster for most users)
$wgMathJaxPath = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js';

Note the comment about the CDN. If you host MathJax yourself, replace the URL with something like /resources/mathjax/tex-mml-chtml.js. Hosting it locally reduces external requests but adds to your bandwidth usage – a trade‑off you’ll need to weigh.

Step 4: Configure the rendering mode

MathJax 3 supports several output processors. The most common is chtml (Common HTML) because it’s lightweight and works on older browsers. If you need higher fidelity, switch to svg. Example:

$wgMathJaxConfig = [
    'tex' => [ 'inlineMath' => [ [ '\\(', '\\)' ] ], 'displayMath' => [ [ '\\[', '\\]' ] ] ],
    'options' => [ 'renderOutput' => 'chtml' ]
];

That snippet tells MathJax which delimiters to watch for and which output to produce. Feel free to tinker – the official MathJax docs list dozens of options, from custom macros to input‑validation hooks.

Writing math in your wiki pages

Once the extension is live, you can embed formulas in three canonical ways. Pick the style that fits the article’s tone.

Inline equations

Wrap the LaTeX code in \$ … \$ or <math>…</math> tags. Example:

The quadratic formula is \\(x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}\\).

In the rendered page you’ll see a smooth, properly sized expression sitting snugly between the words.

Display equations

For larger expressions, use double dollars or the <math display="block"> attribute. Example:

$$
\\int_{-\\infty}^{\\infty} e^{-x^2} \\,dx = \\sqrt{\\pi}
$$

MathJax will centre the formula and give it a bit of breathing room.

Using the `<math>` tag directly

This is the syntax the native Math extension understood, but MathJax respects it too. It’s handy when moving content from an older wiki:

<math>
\\frac{d}{dx} \\sin(x) = \\cos(x)
</math>

Performance considerations

Loading MathJax adds roughly 150 KB of JavaScript to every page that contains math. That’s not trivial, but there are ways to keep the impact modest.

Conditional loading – MathJax only loads when a page actually contains a <math> tag or the delimiters appear. The extension sets a tiny detector script to scan the HTML before fetching the library.
Cache control – If you serve MathJax from a CDN, the file benefits from global caching. If you self‑host, configure Expires headers to a year or more.
Combine with other assets – Many wikis already pull jQuery, Vector skin assets, etc. Bundling MathJax with those (via a build tool) can shave off a round‑trip.

In practice, users on a decent broadband connection notice less than a half‑second delay. Mobile users on slower networks might feel more, but the graceful degradation to plain text (when JavaScript is disabled) keeps the content readable.

Common pitfalls and how to avoid them

Even a seasoned admin can run into snags. Here are a few that show up repeatedly on forums and mailing lists.

MathJax not rendering

First, inspect the page source. Do you see the <script src="…mathjax…"> line? If not, double‑check the $wgMathJaxPath variable. Next, open the browser console – any errors about MathJax undefined point to a broken path or a conflict with another script.

Mixed delimiters causing chaos

When you mix \$...\$ and $$...$$ in the same article, MathJax may misinterpret line breaks. The solution is consistency: stick to one pair of delimiters for inline and another for display. If you inherit a wiki with a hodgepodge of styles, run a quick find‑replace on the dump before importing.

Performance spikes on busy pages

Pages peppered with dozens of equations can trigger a noticeable pause during the initial typeset. A handy trick is to enable fast-preview in the MathJax config, which shows a low‑resolution placeholder while the full render finishes.

$wgMathJaxConfig['options']['fastPreview'] = true;

Accessibility concerns

MathJax offers speech‑output hooks for screen readers. To activate them, add the MathJax-AssistiveMML stylesheet:

$wgMathJaxAssistiveMML = true;

That little flag makes the generated MathML invisible but reachable by assistive technologies, closing the gap for visually impaired users.

Advanced tweaks – making MathJax truly yours

If you’re comfortable tweaking JavaScript, you can extend the renderer with custom macros. For instance, define a macro for the Dirac delta:

MathJax = {
  tex: {
    macros: {
      delta: '\\\\delta\\left(#1\\right)'
    }
  }
};

Now writing \\delta{x} produces δ(x) without typing the whole command each time. The macro file can live alongside your LocalSettings.php and be loaded via the $wgMathJaxConfig['tex']['macros'] array.

Another neat feature is the loader option, letting you pull in only the TeX input processor and the CHTML output, shedding the extra MathML and SVG chunks. That reduces the download size by about 30 % – a win for low‑bandwidth users.

$wgMathJaxConfig = [
    'loader' => [ 'load' => [ 'input/tex', 'output/chtml' ] ],
    // other settings...
];

Bridging MathJax and Semantic MediaWiki

Some wikis use Semantic MediaWiki (SMW) to annotate formulas as data. While the core MathJax extension focuses on rendering, it plays nicely with SMW’s property system. Store a LaTeX string in a property, then display it with {{#ask: [[Formula::+]] | ?Formula= | format=ulist }}. The output will automatically be passed through MathJax, letting you query and visualise mathematical knowledge side by side.

Wrapping up

Integrating MathJax into MediaWiki isn’t a moon‑shot project; it’s a handful of steps and a sprinkle of configuration. The payoff, however, is tangible: equations that look right, load fast, and stay accessible across devices. Whether you run a university’s course notes, a collaborative research portal, or a hobbyist math blog, adding MathJax gives your content the polish it deserves without overburdening the server.

So, when you next glance at a page full of dangling backslashes, ask yourself: “Wouldn’t this be nicer with MathJax?” The answer, for most wikis, is a resounding “yes.”