Gianni Petrella—Transitioning from Mathjax to KaTeX

So far, this website has been using Mathjax to render $\LaTeX$ snippets. This has worked well, and I have never bothered to think about it, until I read this very interesting blog post on website accessibility by Alastair Davidson: https://mohkohn.co.uk/writing/html-first/.

This struck a chord with me, in part because accessibility is good, and in part because I grew up with a very poor internet connection – the quality of my signal would depend on the weather, so if it was raining I could literally not hold Skype calls.

I remember well the frustration of having to wait until several Megabytes of Javascript were delivered to my machine just to read some text, and while this is not a problem for me anymore (one of the perks of living in a big city is good internet, at least), I still like for my software to be optimised and not consume unnecessary resources.

This is why today I switched the math rendering on this website from client-side Mathjax to server-side KaTeX. Now the client browser no longer has to make calls to Cloudflare or to jsdeliver.net, the $\LaTeX$ is rendered to HTML server-side at build time, and now my blog serves strictly static pages.

For you, the reader, absolutely nothing should have changed. In fact, unless you know how to use the inspect function of your browser, you should have no way of noticing the difference at all. Now however, you could decide to have your adblocker disable Javascript, and still read properly rendered mathematics on this blog.

How did I do that?

Here I list the exact steps I took to make the switch, mainly so I don’t forget them, but also in the hope that some other Jekyll user finds them useful.

Run bundle add kramdown-math-katex in your blog’s root folder. Your Gemfile should contain something like this now:

  group :jekyll_plugins do
   gem your-other-gems
   ...
   gem "kramdown-math-katex"
  end

You have to explicitly tell Jekyll to use the kramdown markdown formatter, which supports KaTeX by default. Concretely, your Jekyll _config.yml should contain the following:
```
  markdown: kramdown
  kramdown:
   math_engine: katex
```
and
```
  plugins:
  - your-other-plugins
  ...
  - kramdown-math-katex
```
At this point, KaTeX is rendering properly, but it needs to be styled. In your _includes/head.html file, you should tell the client browser to use the KaTeX CSS stylesheet.

This is done either by including

   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css" crossorigin="anonymous">

or by copying the .css file above, including it in your /css folder and tweaking it at will. I have done the latter, removed the fonts that KaTeX provides and added the following to _includes/head.html:

 <!-- First stylesheet is for katex, then main.css overrides whatever it needs to -->
 <link rel="stylesheet" href="/css/katex.css">
 <link rel="stylesheet" href="/css/main.css">

Readings

Useful resources include:

Xuning Yang’s blog post about this very topic: https://www.xuningyang.com/blog/2021-01-11-katex-with-jekyll/. Note that it is slightly outdated, and now Jekyll users should use plugins instead of gems.
This issue tracker: https://github.com/linjer/jekyll-katex/issues/35. About this: if Google or an LLM suggest you use the jekyll-katex plugin, be aware that it is deprecated and you probably do not want to do that.
Asking an LLM: I used whichever model the free version of Github copilot gave me access to, and it roughly guided me in the correct direction.