Using MathJax to render formulas in LaTeX syntax on (Hugo) websites
Motive
I was just about to start writing the second post in my series about noise and noise diodes when I (again) stumbled upon a problem: I needed to render Schottky’s Formula on the generation of Shot Noise in conjunction with (anode) current - this one:
Now, this problem had hit me in one way or the other ever since I had started publishing on the web: how to render mathematical fomulas. But this time I wanted to do things right…
Formulas and the Web
Considering the fact that Tim Berners Lee invented HTML and HTTP, the fundamental technologies of the WWW, as a means to publish and exchange scientific online content, it often comes as a surprise that publishing scientific (particularly mathematical) formulas nowadays, more than three decades after the WWW’s invention, still is quite a tedious and daunting task.
This is quite intriguing not only considering the Web’s original purpose but even more as already back in 1977 Donald E. Knuth had invented TeX a typesetting program particularly suited for scientific content. And already during the 1980’s LaTeX, originally a set of TeX macros, was the tool of choice for all kinds of publication in academia.
But for quite a long time the only online possibilities to publish formulas on websites were to either render them into graphics and publish them as pictures (originally often GIF or PNG, later SVG) or to improvise using web typography or even ASCII art. The latter at least gave the site a really nerdy touch… Still, no really satisfying solutions.
It was only in 1998 that MathML, an XML language, was recommended as a W3C standard for the display of mathematical formulas in websites. But despite still being actively developed, it has never gained widespread use, mainly due to quite limited browser support, but possibly also because some people consider it’s use being not very intuitive.
So other soultions were sought after and Java Script came to the rescue.
MathJax
Enter MathJax. “A JavaScript display engine for mathematics that works in all browsers.
No more setup for readers. It just works." it says on their website. Quite true for most use cases.
As of version 3 of MathJax it’s basically a matter of including 2 lines of Java Script in a section of the website that finally should include the mathematical formulas and then to include the mathematical formulas in LaTeX syntax into the HTML, surrounded by delimiter characters (by default \( and \) for inline (i.e. formulas included in running text), resp. \[ and \] for display style (i.e. formula as a separate prargraph) maths). The MathJax doocumentation provides a nice example for JS Bin.
As almost all content on the web nowadays is not created and edited in plain HTML, but backed by some sort of content management (CMS) and/or authoring system, several plugins for virtually all common CMSs are available. But how about Hugo, a static website generator building sites from (mainly) content written in Markdown format? Basically there’s not much of a difference, as markdown files can be complemented by plain HTML code included into the markdown file and therefore one can include the MathJax library just like one would do in plain HTML. At least almost…
Hugo/Markdown & MathJax Quirks
A quick keyword search on hugo and mathjax on the web inevitably gets you to this site and it does indeed (though still based on MathJax version 2) provide almost all necessary information, especially pointing out the possible pitfalls when using MathJax with Hugo.
Basically it all boils down to the fact that Hugo (precisely the markdown rendring engine - Goldmark it is by default) interacts with the LaTeX code input to MathJax. Especially the backspace character \ will be interpreted as an escape character and removed from the output of the markdown renderer, thus never approaching the (Java Script) MathJax engine. Similarly underscores _ will (by means of markdown standard) lead to italic text and the undescore character removed from the output. But in case of a (LaTeX) formula the underscore is used for creating subscripts.
So clearly the challange is to find a way that allows all LaTeX code designated for MathJax to pass the markdown renderer totally unchanged. You find additional explanations and several ways to work aound this problem on the aforementioned website. I will focus here on the (very pragmatic!) solution I sucessfully tested and I’m going to use in the future.
A Pragmatic Appoach
Below I will use the example formulas from the MathJax website for demonstration purposes, as it shows all necessary techniques for successfully rendering formulas on websites.
General
To make use of MathJaX the first step is to include the MathJax code in an appropriate place of the website. I decided to use the footer template (/layouts/partials/footer/site-footer.html in this site’s particular case) as this partial is included in every page of the website:
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3.0.1/es5/tex-mml-chtml.js"></script>
I chose to include the code from MathJax' CDN, but local delivery would be possible as well. The second line basically configures MathJax for TeX or MathML input, generating common HTML output. Usually there’s no need to change this default setting, but in case different input or output formats are needed, all available combinations are provided in the MathJax documentation.
Inline Formulas
This is the more cumbersome use of MathJax with Hugo, mainly due to the contstraints already mentioned above. As ususally he use of inline math is much rarer compared to display style maths, the easiest approach to get useful results is by simply escaping all LaTeX code using backslashes \. E.g. the following (slightly altered) example from the MathJax website (prerequisites for solving common quadradic equations)
When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) ...
can be changed into
When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c = 0\\) ...
which finally gets rendered into:
When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) …
Note: of course display style math can be processed this way, too - but there’s a better way to do so.
Display Style Formulas
The approach here is pretty straight forward, we make use of the fact that all text inbetween <div> and </div> tags in markdown will stay untouched by the markdown renderer therfore being directly passed to MathJaX. So implementing display style maths simply boils down to including the MathJax Java Script code and then to include MathJaX delimiters and the formula’s LaTeX code within the <div> </div> section.
To make this possible it is necessary to enable inline HTML in the markdown code (by default goldmark refuses to render plain HTML due to security concerns (we should keep this in mind!) by adding
[markup.goldmark.renderer]
unsafe = true
to your site’s config.toml main configuration file.
So, to continue the above example this code
<div>
\[x = {-b \pm \sqrt{b^2-4ac} \over 2a}\]
</div>
will get rendered as such:
Putting it all together
So by using both techniques we finally get to this code
When \\(a \ne 0\\), there are two solutions to \\(ax^2 + bx + c = 0\\) and they are
<div>
\[x = {-b \pm \sqrt{b^2-4ac} \over 2a}.\]
</div>
which will be rendered into:
When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are:
Pretty nice, isn’t it?
References
There’s (at least) one more benefit using <div> sections for display style maths: You can easily use id’s to reference your formulas
<div id="formula_xy">
[formula code goes in here]
</div>
and elsewhere on the page link to it (HTML style): <a href="formula_xy">Link</a>
or (Markdown style): [Link](#formula_xy)
Like in this example from this site :-)
Conclusions and Outlook
MathJax appears to be the solution for rendering mathematical formulas, a common problem in technical online publishing. And using above pragmatic approach for inline and display type math makes MathJax use with Hugo/Markdown a piece of cake. Even numbering and referencing the (display style) formulas is simple, provided rudimentary HTLM knowlegde is at hands.
So - a perfect solution? Not quite so, unfortunately, as there’s one crucial matter missing: An easy possibility to use the same text base for different publishing purposes. Clearly something for a future project involving LaTeX/BibteX and/or Zotero, Pandoc and possibly other tools to build a publishing system that creates output for the Web, print (articles, books) or eBooks.
And there are additional things to be tested in the future. E.g. the Goldmark MathJax Extension, though right now this doesn’t seem to be a straight forward approach as it needs manual compilation of the Goldmark and Hugo source codes (see this discussion) - honestly I was just way too lazy to follow this path right now, future trials not ruled out.
