Jun 12, 2021

How to Add Math Expressions to Hugo Blog - the Shortest Guide Possible

Want your blog to include Math Expressions, like the Mass–energy equivalence formula?

$$ E=mc^2 $$

Or L’Hôpital’s rule?

$$ \mathop {\lim }\limits_{x \to c} \frac{{f\left( x \right)}}{{g\left( x \right)}} = \mathop {\lim }\limits_{x \to c} \frac{{f’\left( x \right)}}{{g’\left( x \right)}} $$

Or Matrix Multiplication?

$$ \begin{pmatrix} 0 & 1 \\ 0 & 0 \end{pmatrix}\begin{pmatrix} 0 & 0 \\ 1 & 0 \end{pmatrix}=\begin{pmatrix} 1 & 0 \\ 0 & 0 \end{pmatrix} $$

Here’s the shortest guide I can write for you. This guide assumes you’re blogging with Hugo, like this blog. Read my “How to build this blog” post to learn how to set something like this up.

Table of Contents

1. Fork your blog’s theme

We’re going to change the blog’s theme, so we want to fork the theme we’re using, so we can commit and push changes without bothering anyone. Maybe even merge the changes back to the original project later on!

In my case I’m using hermit. In the theme’s GitHub page, click “Fork”:

forking example

Then, locally added the forked theme as a submodule using

# Assuming you're in your blog's root dir
cd themes

# This is my command, for example
git submodule add https://github.com/TheCoreMan/hermit hermit-fork

# Yours should be
git submodule add https://github.com/<your usename here>/<theme name here> <theme name here>-fork

Finally, edit your config.toml file so that Hugo uses your new, forked theme:

theme = "hermit-fork"

2. Choose where to include JS scripts

EDIT: I’ve discovered that adding to baseof.html harms performance. I’ve moved the JS to single.html instead, and also wrapped it in a conditional. See this post for details.

To display math we’re going to use a JS script. We’ll include the JS in our layouts/_default/baseof.html file, to make sure that we have Math support in every single page. You can choose different places to include the JS, such as layouts/_default/header.html, layouts/_default/footer.html or layouts/_default/single.html - your mileage may vary based on your theme’s setup.

3. Add MathJax JavaScript

MathJax is a JavaScript display engine for mathematics. To use it, we need to add the MathJax script to the page we’ve chosen. Copy and paste this snippet to your the layout snippet you’ve chosen to add JS to:

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

<!-- this part configures it -->
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  tex2jax: {
    inlineMath: [['\\(','\\)']],
    displayMath: [['$$','$$'], ['\[','\]']],
    processEscapes: true,
    processEnvironments: true,
    skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
    TeX: { equationNumbers: { autoNumber: "AMS" },
         extensions: ["AMSmath.js", "AMSsymbols.js"] }
  }
});
</script>

If you need any specific configurations, prefer to host the JS yourself (for local publishing/avoiding CDN outbreaks) or want to customize anything else, you can find MathJax’s installation documentation here.

Here’s specific documentation about the configuration values we’re using here: tex2jax input configruation. Specifically important:

  • processEscapes - this will help avoit messing up normal markdown.
  • skipTags - without this, MathJax will try to parse parts of our post which we don’t want it to

4. Test using a math expression in your markdown posts

Now that we’re done with setup, let’s see how to use Math Expressions in our markdown posts.

Inline math expressions

To get an inline math expression like \(E=mc^2\), wrap your math expression with \\( and \\), like so: \\(E=mc^2\\).

Display math expressions

This markdown:

$$ E=mc^2 $$

Produces this math expression:

$$ E=mc^2 $$

You can also use \\[ and \\] as delimiters, like so:

\\[ E=mc^2 \therefore E_{\rm rel} = \sqrt{ (m_0 c^2)^2 + (pc)^2 } \,\! \\]

\[ E=mc^2 \therefore E_{\rm rel} = \sqrt{ (m_0 c^2)^2 + (pc)^2 } ,! \]

Complicated math expressions

This markdown:

$$ \mathop {\lim }\limits\_{x \to c} \frac{{f\left( x \right)}}{{g\left( x \right)}} = \mathop {\lim }\limits\_{x \to c} \frac{{f'\left( x \right)}}{{g'\left( x \right)}} $$

Produces this math expression:

$$ \mathop {\lim }\limits_{x \to c} \frac{{f\left( x \right)}}{{g\left( x \right)}} = \mathop {\lim }\limits_{x \to c} \frac{{f’\left( x \right)}}{{g’\left( x \right)}} $$

NOTE: We had to escape (i.e. put a \ before) our underscores. Make sure to turn all _ into \_ inside your math expression. That’s because underscores mark italicized text in markdown, and our parser might mess up the Math Expression, so MathJax won’t be able to read it.

Multiline expressions

This markdown:

$$ \begin{pmatrix} 0 & 1 \\\\ 0 & 0 \end{pmatrix}\begin{pmatrix} 0 & 0 \\\\ 1 & 0 \end{pmatrix}=\begin{pmatrix} 1 & 0 \\\\ 0 & 0 \end{pmatrix} $$

Produces this math expression:

$$ \begin{pmatrix} 0 & 1 \\ 0 & 0 \end{pmatrix}\begin{pmatrix} 0 & 0 \\ 1 & 0 \end{pmatrix}=\begin{pmatrix} 1 & 0 \\ 0 & 0 \end{pmatrix} $$

NOTE: We had to escape (i.e. put a \ before) our backslashes TWICE. Make sure to turn all \\ into \\\\.

Attribution: Vector Vectors by Vecteezy.

See Also