MathJax 2 to 3 Migration Guide (and What Changes in MathJax 4)

MathJax 3 is a complete rewrite of MathJax 2, so upgrading means changing how you load, configure and call MathJax. MathJax 4 keeps the version 3 API and mainly changes fonts and line breaking. This guide walks through each change with before-and-after code.

Step 1: Replace the script tag

MathJax 2 loads MathJax.js with a ?config= parameter. MathJax 3 and 4 load a single combined component file instead. Pick the file that matches your old configuration:

The CDN paths differ slightly between versions. MathJax 3 files live in an es5/ folder:

<!-- MathJax 2 -->
<script src="https://cdn.jsdelivr.net/npm/mathjax@2.7.9/MathJax.js?config=TeX-AMS_CHTML"></script>

<!-- MathJax 3 -->
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>

<!-- MathJax 4 -->
<script src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-chtml.js"></script>

Step 2: Convert your configuration

MathJax 2 reads configuration from a text/x-mathjax-config script that calls MathJax.Hub.Config(). MathJax 3 and 4 read a plain window.MathJax object, which must be defined before the MathJax script loads.

Before (MathJax 2)

<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    tex2jax: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      processEscapes: true
    },
    TeX: {
      extensions: ['mhchem.js'],
      Macros: { RR: '{\\bf R}' }
    }
  });
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@2.7.9/MathJax.js?config=TeX-AMS_CHTML"></script>

After (MathJax 3 and 4)

<script>
  window.MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      macros: { RR: '{\\bf R}' }
    }
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>

What changed in this example:

• tex2jax options moved into the tex block.
• TeX.Macros became tex.macros (lowercase).
• processEscapes is on by default in MathJax 3 and 4, so \$ already shows a literal dollar sign.
• The mhchem line is gone: MathJax 3 and 4 load mhchem automatically the first time \ce or \pu is used.

Step 3: Update code that re-renders math

If your page adds math after loading (for example in a React, Vue or Angular app), the typesetting calls change too:

typesetPromise calls must not overlap. A safe pattern is to chain every call onto the startup promise:

function typeset(elements) {
  MathJax.startup.promise = MathJax.startup.promise
    .then(() => MathJax.typesetPromise(elements))
    .catch((err) => console.error('Typeset failed:', err));
  return MathJax.startup.promise;
}

Step 4: Check extensions and behaviour changes

• \color works like LaTeX now. In MathJax 2, \color{red}{x} + y colours only x. In MathJax 3 and 4, \color is a switch, so + y turns red too. Use \textcolor{red}{x} or {\color{red} x}, or load the colorv2 extension to keep the old behaviour.
• mhchem is newer. MathJax 2.7 uses an older mhchem by default, while MathJax 3 and 4 use the current version. Some reactions can render differently; see the mhchem examples.
• HTML-CSS output is gone. MathJax 3 and 4 offer CommonHTML (chtml) and SVG output only.
• Ignore classes were renamed. tex2jax_ignore and tex2jax_process are now mathjax_ignore and mathjax_process.
• AsciiMath must be loaded separately. The combined files don't include it; add loader: { load: ['input/asciimath'] } to your configuration.
• No automatic line breaking in MathJax 3. MathJax 2 can break long equations when you set CommonHTML: { linebreaks: { automatic: true } } (it's off by default). MathJax 3 has no equivalent, so long equations overflow. Line breaking returns in MathJax 4.

Step 5: What changes in MathJax 4

Code written for MathJax 3 mostly works in MathJax 4 unchanged. The differences you'll notice:

• New default font. MathJax 4 uses mathjax-newcm, based on New Computer Modern, which covers many more characters. Glyph shapes and spacing can look slightly different from version 3.
• Line breaking is back. Long inline math wraps by default at top-level operators such as + and =, but not inside brackets like (a + b + c)^2. Long display equations still overflow unless you enable breaking:

  window.MathJax = {
    output: { displayOverflow: 'linebreak' }
  };

• No es5/ folder. Load files directly, for example mathjax@4/tex-chtml.js.

Test before you switch

The fastest way to catch rendering differences is to paste real content from your site into the MathJax live preview, which renders it in MathJax 2.7.9, 3.2.2 and 4.1.3 side by side.