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.

hugo local preview no KaTeX macro

public Hugo blog KaTeX auto-renderer error

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!

hugo local preview with KaTeX macro

KaTeX  Mmark  Hugo 

No comment

Your email address will not be published. Required fields are marked *.