Testing to use LaTeX in Github Pages created by Jekyll

So I wanted to add LaTeX to a markdown document.

Try 1: just do it

I googled it and found out that it’s supported and it’s pretty simple: just do this

$$1+1=2$$

When I tried it, my local markdown parser in VS Code was able to render it but the result online on this page looked like this:

\[1+1=2\]

I googled a bit more and found out that it’s not a trivial task. Here’s a long post on Stackoverflow with lots of outdated solutions.

The latest news tells us that Github has released Math support in Markdown. Cool. They are using MathJax to render it.

Try 2: _includes/head.html

Then I tried adding

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

to docs/_includes/head-custom.html. It didn’t work.

Try 3: add Mathjax script to the .html document generated by Jekyll

This possibly outdated source told to add

<script
  src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
  type="text/javascript">
</script>

to my Markdown document (or… HTML document?). I compiled my page locally and it actually worked.

The steps to do this:

cd docs
bundle istall
bundle exec jekyll serve

Then I searched my post .html document in _site and added the script above to the bottom just before `</html>.

then I opened http://127.0.0.1:4000/ on my browser and it rendered my LaTeX correctly!

The problem is now: how do I incorporate these changes to remote as _site is autogenerated by Jekyll?

The small print says:

Just add the HTML code to your layout definition files, e.g., single.html or post.html, and MathJax support gets enabled on all your pages that use these layouts.

Try 4: use layouts incorrectly

The Docs was the next place I went looking. It says:

  • create _layouts folder (if you haven’t got it already)
  • add default.html which will be the default for your posts
  • add post.html that inherits default.html to use for all posts
  • edit those files accordingly

Then I really went and created those files. But I didn’t know what to put there. So I left them empty and compiled my page locally. Then the pages were just blank. Wtf.

Try 5: use layouts correctly by taking the theme into account

Then I realized that I have to write all the html myself to those files if I want to render anything. I haven’t created my own layouts myself but rather used minima. So I realized that I can

  • copy their implementiation of _layouts here
  • paste it to my files
  • add the script
<script
  src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
  type="text/javascript">
</script>

to _layouts/default.html to the end just before the </html> tag. I tried adding it to _layouts/post.html but that didn’t end up well.

Remember that any time you can debug your page by building it locally and checking the generated .html files in _site/ after that.

and just like magic, then my LaTeX worked just fine. Remember that not all LaTeX packages are supported by MathJax. Read more here and here.

It works!

\[1+1 = 2\] \[x^2 = 1\] \[f(a) = \frac{1}{2\pi i} \oint\frac{f(z)}{z-a}dz\] \[\vec{\nabla} \times \vec{F} = \left( \frac{\partial F_z}{\partial y} - \frac{\partial F_y}{\partial z} \right) \mathbf{i} + \left( \frac{\partial F_x}{\partial z} - \frac{\partial F_z}{\partial x} \right) \mathbf{j} + \left( \frac{\partial F_y}{\partial x} - \frac{\partial F_x}{\partial y} \right) \mathbf{k}\]