Upgrading to MathJax v3 and Adding Features

In my previous post, I demonstrated how to integrate MathJax into a Jekyll blog to enable mathematical equation rendering. Upon reviewing the code from that implementation, you can see that we were using MathJax version 2.7.5.

<script type="text/javascript" async
    src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-MML-AM_CHTML">
</script>

While this version was quite functional, there were several reasons to upgrade to the latest stable version 3.0. The two main motivations for this upgrade were:

• Access to the LaTeX physics package
• Better alignment with current documentation and community support

The physics package is particularly valuable for writing various physical notations, and I frequently found myself missing its functionality when writing MathJax expressions using my usual LaTeX conventions. Upon investigation, I discovered that while MathJax provides several LaTeX extensions, the physics package is only available in v3, not in v2.

Additionally, when researching how to implement features like equation numbering, I found that most solutions and documentation were written for v3, making it challenging to adapt the syntax differences. Given both the necessity of the physics package and the clear trend toward v3 in the community, I decided to proceed with the upgrade.

Loading MathJax

The first modification required is to update the script that loads MathJax. Instead of loading version 2.7.5, we’ll now load version 3.0.0. While it’s possible to always load the latest version (reference), this could make the site vulnerable to syntax changes and errors.

... scripts.html excerpt

<script id="MathJax-script" async
  src="https://cdn.jsdelivr.net/npm/[email protected]/es5/tex-mml-chtml.js">
</script>

Configuring MathJax

The configuration code has been significantly simplified in v3:

... scripts.html excerpt

<script>
MathJax = {
  loader:  {
    load: ['[tex]/physics']                    // loader for the physics package
  },
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']],  // math mode delimiters
    packages: {'[+]': ['physics']},            // additional packages
    tags: 'ams'                                // auto-numbering
  }
};
</script>

Enjoy MathJax v3

After completing these steps, you can now utilize MathJax v3 with physics package support. Note that for auto-numbering to work, you must use proper LaTeX numbered equation syntax with environments like equation or align, rather than simple $ delimiters.

\begin{equation} \bra{\psi} = \sum_{\omega} \bra{\omega} \braket{\omega}{\psi} \end{equation}