Getting Mathjax to Work With Hugo

Getting Hugo to work with Mathjax (or vice versa) to create these pages took a little bit of fiddling and some trial-and-error.

1. Change the page templates to include the current version of the mathjax.js library:

   <script type="text/javascript" id="MathJax-script" async
     src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
   </script>
   

2. Out of the box, the normal TeX math delimiters \( .. \) and \[ .. \] did not seem to work. A quick inspection of the generated HTML showed that the Markdown engine “ate” the backslashes. Doubling the backslashes corrected this problem. In other words, inline math has to be surrounded by \\( .. \\) and display math by \\[ .. \\].

3. For inline math, I much prefer dollar-signs as delimiters. By default, Mathjax does not recognize them as delimiters (because they might occur in regular text). This can be changed by including the following script before loading the Mathjax library:

   MathJax = {
       tex: {
           inlineMath: [['$', '$'], ['\\(', '\\)']]
       }
   };
   

At this point, I can use single dollar-signs $ .. $ for inline math, and either double dollar-signs $$ .. $$ or brackets with doubled backslashes \\[ .. \\] to indicate display math.

This implies that I now need to escape them, if I want to actually produce a dollar sign in regular text: \$. But this happens sufficiently infrequently (ever?) that this is a small price to pay.

Several caveats and warnings remain:

1. Be careful with < and > in math mode: they may be misinterpreted as HTML tags! The suggested workaround is to leave space on either side of them. An alternative is to use their command forms: \lt and \gt.

2. Care must be taken with several TeX/LaTeX commands that consist of a backslash followed by punctuation. Markdown engine will consume those backslashes as well, even in math mode. Doubling the backslash restores the desired behavior. This seems to apply to spacing commands like \, and \!, and of course to the backslash itself! Linebreaks in math mode are indicated using \\; both backslashes must be doubled, and hence the linebreak indicator becomes \\\\. Oversized delimiters within math mode should probably be indicated through the \left( and \right) commands to avoid problems.

3. Thankfully, either Hugo or the currently used Markdown engine have been taught to leave underscores in math mode alone, meaning they simply work (and produce subscripts, as intended; while indicating italics outside of math mode.) Apparently, it was not always thus: a quick Google search produces pointers to numerous workarounds, intended to protect underscores in mathmode from being consumed by the Markdown engine. (I am truly grateful for this, but I do live in fear that this behavior might change with the next release of either Hugo or whatever Markdown engine Hugo will use at that time.)

See the bottom of this page for all Markdown escape sequences: https://daringfireball.net/projects/markdown/syntax

The Mathjax page itself gives more detail about possible interactions between Markdown and Mathjax: http://docs.mathjax.org/en/latest/input/tex/html.html (see the section “Interaction with Content-Management Systems”)