Improved Integration of Hugo and $\KaTeX$

Problem

There’s no custom $\KaTeX$ macro in local preview since I’ve merged some recent commits from the upstream of this blog’s theme, in particular, Beautiful Hugo’s pull requests #246 and #255, which allowed self-hosting the theme’s static JS, CSS and font files. This self-hosted option is particularly useful in case of slow response from Cloudflare’s CDN.

Even they do appear on the public GitLab site, the final rendered Markdown + $\TeX$ code would be succumb to syntax errors due to their absence in the preview process.

Solution

General method

Searching “Hugo KaTeX”, I’ve found Edwin Kofler’s blog post about Hugo + $\KaTeX$ useful.

Just choose Mmark, which is a fork of Blackfriday, a popular Markdown processor for Go, as the post’s Markdown parser by either

1. adding the option markup: mmark in the content’s front matter; or
2. changing the content file’s extension name to .mmark.

After that, Hugo recognised the inline and display math by a pair of surrounding $$. It wouldn’t try to interpret the underscores _ inside a pair of $$. The difference between inline and display math is whether $$ occupies one entire line.

Difficulties

Repeated custom $\KaTeX$ delimiters

I’ve added Showdown for static comment preview in static/js/staticman-preview.js in my tweaked Beautiful Hugo theme. This JS file also contains lines that convert $$ ... $$ into math expresions.

$( document ).ready(function() {
  var myKaTeXOptions = {
    // LaTeX like math delimiters
    delimiters: [
    {left: "$$", right: "$$", display: true},
    {left: "\\[", right: "\\]", display: true},
    {left: "$", right: "$", display: false},
    {left: "\\(", right: "\\)", display: false}
    ],
    throwOnError: false
  };

  ...
});

My custom $\KaTeX$ macros not recognised

I’ve created some custom $\KaTeX$ macros to simplify the math writing process. However, they won’t work without the lines containing $ in the delimiters in static/js/katex-macros.js. As a result, I have to put back these two lines at commit 9e640f21. In case of custom macros, I still need to rely on those two lines and the surrounding <div> tag, but I can put markup: mmark in the posts’ front matter.

Existing $\TeX$ inline math markup

I prefer $\TeX$’s way of inline math markup $ ... $ over its Blackfriday counterpart $$ ... $$. Systematically replacing the former by the later would be a formidable task. I’ve given that up in favour of one single line $ in delimiters.

Chores: Format the math

The content/ changes at commit 9e640f21 can be categorized into:

• inline math: unescaped underscores _.

  Lorem ipsum $$ s_1 = a_2 \times p_3 $$.
  

• display math: surrounding $$’s and empty lines needed. Unwrapped <div> for normal block equations.

  Lorem ipsum.
  
  $$
  s_1 = a_2 \times p_2
  $$
  

• manual custom macro detection and review

Results

My custom macros have finally come back!