The SimpleMathJax extension uses MathJax 4 to typeset TeX formulas in MediaWiki.
It supports <math> and <chem> tags and follows the display conventions of the Math extension.
Einstein's mass-energy relation is <math>E=mc^2</math>.
<math display="block">a^2 + b^2 = c^2</math>
<chem>CO2 + C -> 2 CO</chem>
- Features
- Simple and lightweight
- VisualEditor support
- MathJax 4 with UTF-8 and mobile support
<math> and <chem> parser tags- MediaWiki-compatible inline and block display modes
- Optional scanning for bare inline and display delimiters
- Configurable output scale, context menu, HTML attributes, and revision-based overrides
Installation
- Download and place the file(s) in a directory called
SimpleMathJax in your extensions/ folder.
- Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'SimpleMathJax' );
- Configure the extension if necessary
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Alternatively, clone the repository into your MediaWiki extensions directory.
$ git clone https://github.com/jmnote/SimpleMathJax.git
The CDN is enabled by default.
To use the bundled local MathJax copy, clone the submodule as well and set $wgSmjCdnEnabled to false.
$ git clone --recursive https://github.com/jmnote/SimpleMathJax.git
wfLoadExtension( 'SimpleMathJax' );
$wgSmjCdnEnabled = false;
SimpleMathJax is intended as an alternative to the Math extension.
Do not enable both extensions: they register the same <math> and <chem> parser tags and may conflict.
Configuration
Define configuration variables in LocalSettings.php after calling wfLoadExtension( 'SimpleMathJax' );.
| Setting
|
Default
|
Description
|
$wgSmjCdnEnabled
|
true
|
Load MathJax from a CDN instead of the bundled local copy.
|
$wgSmjCdnVersion
|
'4'
|
MathJax version loaded from the CDN. Use an exact version such as '4.1.3' to pin it.
|
$wgSmjScale
|
1
|
Value passed to MathJax.chtml.scale.
|
$wgSmjEnableMenu
|
true
|
Enable the MathJax context menu.
|
$wgSmjDelimitersEnabled
|
false
|
Scan page text outside <math> and <chem> for configured bare delimiters.
|
$wgSmjDelimitersInlineMath
|
[]
|
Inline delimiter pairs used when extra delimiter scanning is enabled.
|
$wgSmjDelimitersDisplayMath
|
[]
|
Display delimiter pairs used when extra delimiter scanning is enabled.
|
$wgSmjAllowedAttributes
|
[]
|
Generic HTML attributes allowed to pass from a math or chem tag to its output <span>.
|
$wgSmjIgnoreHtmlClass
|
comment|diff-(context|addedline|deletedline)'
|
Regular-expression fragment for HTML classes MathJax must ignore.
|
$wgSmjRevisionOverrides
|
[]
|
Configuration overrides selected by page revision ID.
|
CDN and local MathJax
The default CDN setting follows the latest MathJax 4.x release. Set an exact version to pin it, or disable the CDN to use the bundled copy:
wfLoadExtension( 'SimpleMathJax' );
// Pin the CDN version:
$wgSmjCdnVersion = '4.1.3';
// Or use the bundled local copy:
$wgSmjCdnEnabled = false;
Scale and context menu
$wgSmjScale is a multiplier for the output font size.
$wgSmjEnableMenu controls the MathJax right-click context menu.
$wgSmjScale = 1.5;
$wgSmjEnableMenu = false;
Extra delimiters
Version 1.0.0 recognizes only <math> and <chem> by default.
To recognize bare delimiters such as $...$ and $$...$$, enable delimiter scanning and configure the pairs explicitly:
$wgSmjDelimitersEnabled = true;
$wgSmjDelimitersInlineMath = [ [ '$', '$' ], [ '\(', '\)' ] ];
$wgSmjDelimitersDisplayMath = [ [ '$$', '$$' ], [ '\[', '\]' ] ];
When delimiter scanning is enabled, keep the default $wgSmjIgnoreHtmlClass pattern unless you deliberately need to change it; it prevents literal delimiters in comments and diff views from being typeset.
HTML attributes
No generic HTML attributes are copied by default.
Add only the attributes that wiki editors need; values still pass through MediaWiki's attribute sanitizer.
The rendering-control attributes display and chem always work and do not need to be listed.
$wgSmjAllowedAttributes = [ 'class', 'title' ];
Revision-based configuration
Use $wgSmjRevisionOverrides to preserve historical rendering behavior for specified revision-ID ranges.
The min and max bounds are inclusive; omit either one for an open-ended range.
Later matching entries override earlier ones.
Preview, history, and special pages use the base settings.
$wgSmjDelimitersEnabled = false;
$wgSmjRevisionOverrides = [
[ 'max' => 50000, 'wgSmjDelimitersEnabled' => true ],
[ 'min' => 50001, 'max' => 60000, 'wgSmjDelimitersEnabled' => false ],
];
Display modes
SimpleMathJax follows MediaWiki Math's display conventions:
| Syntax
|
Layout
|
TeX style
|
<math>...</math>
|
Inline
|
\displaystyle
|
<math display="inline">...</math>
|
Inline
|
\textstyle
|
<math display="block">...</math>
|
Block, centered
|
\displaystyle
|
The <chem> tag automatically wraps its contents in MathJax's \ce{...}.
The form <math chem> only preloads the mhchem package, so include \ce{...} yourself when using it.
<chem>CO2 + C -> 2 CO</chem>
<math chem>\ce{CO2 + C -> 2 CO}</math>
Hooks
The SimpleMathJaxAttributes hook can modify the attributes of the output <span> for <math> and <chem> elements.
For example, the following prevents the Lingo extension from modifying formula contents:
$wgHooks['SimpleMathJaxAttributes'][] =
function ( array &$attributes, string $tex, array $args = [] ) {
$attributes['class'] .= ' noglossary';
};
Upgrading to 1.0.0
Version 1.0.0 requires MediaWiki 1.43 or later and redesigns the configuration without backward compatibility.
Renamed or removed settings are no longer read; the unchanged $wgSmjScale, $wgSmjEnableMenu, $wgSmjIgnoreHtmlClass settings continue to work.
In particular, bare delimiter scanning now defaults to off.
| Before 1.0.0
|
1.0.0
|
$wgSmjUseCdn
|
$wgSmjCdnEnabled
|
$wgSmjDirectMathJax
|
$wgSmjDelimitersEnabled
|
$wgSmjExtraInlineMath
|
$wgSmjDelimitersInlineMath
|
$wgSmjDisplayMath
|
$wgSmjDelimitersDisplayMath
|
$wgSmjEnableHtmlAttributes
|
$wgSmjAllowedAttributes
|
$wgSmjConfigByRevision
|
$wgSmjRevisionOverrides
|
$wgSmjUseChem
|
Removed; <chem> is always enabled
|
$wgSmjDisplayAlign, $wgSmjWrapDisplaystyle
|
Removed; display behavior now follows MediaWiki Math
|
Revision override bounds were also renamed from since/upto to min/max.
See the complete 1.0 migration guide before upgrading an existing wiki.
The old inline-block attribute was also removed.
Plain <math>…</math> is now inline with display-style sizing; use display="inline" for text-style sizing or display="block" for a centered block.
Samples
- Comparison
- More examples
See also
External links
 | This extension is included in the following wiki farms/hosts and/or packages: |
