Using LaTeX in Jekyll with MathJax

You may have noticed that my last blog post had some LaTeX-looking formulae formatted all nicely inline. This, sadly, took me the better part of the last few hours which only took away from my actual studying time, so I figured a blog post was in order to save everyone else the headache. To do this, I combed through multiple Stack Overflow pages and blog posts, but what ultimately saved me was simply RTFM.

The main thing you need to know is that this website uses Jekyll, which is what Github Pages uses to transform markdown into a spiffy website. I’m not going to go into the details of how to set up your own site using Github Pages right now (maybe a topic for a later blog post?), mostly because I set this up over six years ago. But just in case you are already using Jekyll, I want to give you the lowdown on adding LaTeX. In order to use LaTeX in markdown, you have to use MathJax. According to their documentation, “MathJax is an open-source JavaScript display engine for LaTeX, MathML, and AsciiMath notation”. Great, just what we need.

So, a lot of the information out there is either wrong or broken, and I suspect this is partially due to the fact that MathJax is now on version 3.2.1 which is quite different from 2.x. If you are currently using MathJax v2, I found this webpage describing how to upgrade. However, if you’re starting from scratch, here’s what you’re gonna do.

  1. In your _includes folder, create a new file under _includes/head/custom.html.
  2. In that file, put the following code:
<script>
MathJax = {
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']]
  },
  svg: {
    fontCache: 'global'
  }
};
</script>

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

Note: I got this directly from the MathJax documentation, under “Using a Local File for Configuration”. If what’s on that page has changed from this code block, go ahead and use that.
3. In your _layouts/default.html file (which should already exist), you’re going to include the above file by adding the line {% include head/custom.html %} to your header–the codeblock within the <head>...</head>.
4. You can then test that this works by writing a formula in one of your posts. You can use single regular dollar signs to encode inline LaTeX, or double dollar signs to have the formula on its own line. Because dollar signs are now used for math, you’re going to have to escape them every time you use them as a literal. If you don’t want to do this, you can remove them from the line beginning with inlineMath on your head/custom.html file, but then you have to use \( and \) to start and end your inline math.

And that’s it! It was really a lot easier than I made it on myself, and hopefully this helps you out too. A couple things to note about LaTeX if you haven’t used it in awhile, like myself:

  • To do a fraction, you simply type $\frac{numerator}{denominator}$, filling in your numerator and denominator in the two sets of braces.
  • By default, the text will be italicized and there will be no spaces in between words. If you want spaces and/or non-italicized text, encircle your text with \text{...}.
  • An underscore will make the next character subscript like this: $H_0$ will come out as $H_0$. If you want an underscore literal you should be able to escape it like this \_ but that was giving me trouble. When I kept my underscore within the \text{...} brackets, however, this wasn’t a problem. I used my underscores in variable names so they were encircled in the \text{...} bracket anyway.

Happy mathing!

–Em

Written on June 25, 2022