Render TeX in Hugo Blog

Recently, I started to think about learning $\TeX$, adding $\TeX$ support to blog looks like a good start for me. It took me quite some time to figure out all the culprits of embedding $\TeX$ in markdown. I hope this blog could save you some time before starting writing in $\TeX$.

Note: Some contents in this post is outdated. Hugo markdown engine moved from Blackfriday to Goldmark.

Required Components

• The default Blackfriday markdown engine.
• $\KaTeX$ math typesetting library for the web.

Steps to Setup $\KaTeX$ in Hugo

$\KaTeX$ is an excellent fast engineer for rendering $\TeX$ on web. The $\KaTeX$ Auto-render Extension is an extension to automatically render all of the math inside of text.

Example:

Code:

1
2
3
4

\def\f#1#2{#1f(#2)}
\f\relax{x} = \int_{-\infty}^\infty
    \f\hat\xi\,e^{2 \pi i \xi x}
    \,d\xi

Integrate $\KaTeX$ Auto-render Extension

The first step is to find the right place to include the $\KaTeX$ Auto-render Extension. It is different by theme, usually, the header.html or footer.html could be the ideal place; or, if the theme support math libraries, it may provide a separate HTML, in my case, it is math.html.

Locate the HTML file, create the same directory structure in your project, copy the HTML, and include the library. Here is my math.html, a new parameter katex is defined in it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{{- if .Params.katex -}}
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.css" integrity="sha384-R4558gYOUz8mP9YWpZJjofhk+zx0AS11p36HnD2ZKj/6JR5z27gSSULCNHIRReVs" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.js" integrity="sha384-z1fJDqw8ZApjGO3/unPWUPsIymfsJmyrDVWC8Tv/a1HeOtGmkwNd/7xUS0Xcnvsx" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous"></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {
          // customised options
          // • auto-render specific keys, e.g.:
          delimiters: [
              {left: '$$', right: '$$', display: true},
              {left: '$', right: '$', display: false},
              {left: '\\(', right: '\\)', display: false},
              {left: '\\[', right: '\\]', display: true}
          ],
          // • rendering keys, e.g.:
          throwOnError : false
        });
    });
</script>
{{- end -}}

Enable $\KaTeX$ in Markdown

Enable the parameter katex in the posts which require $\TeX$. Depend on the markdown header format, it could be TOML or YAML.

• TOML

1
2
3
4
5

+++
title = "Render $\\TeX$ in Hugo Blog"
...
katex = true
+++

• YAML

1
2
3
4
5

---
title: "Render $\\TeX$ in Hugo Blog"
...
katex: true
---

Time to Dance

First, The Known Issues

Check the official document for Issues with Markdown and Solution.

• The underscore character _

  It is interpreted by Markdown as a way to wrap text in emph blocks while it is a way to create a subscript in $\TeX$.

  • Escape each underscore in your math code by entering \_ instead of _.
  • Wrap the math expression inside a <div> </div> block.

• The newline \\

  Markdown engineer interprets \\ as <br>, it breaks the $\TeX$.

  • Use \newline instead of \\.
  • Wrap the math expression inside a <div> </div> block.

• Escape slash character\

  • Escape the inline delimiter \\( and \\).
  • Another case I found is the slash in markdown title.

Inline Math

Use $ $ or \( \) as delimiters for inline math. It can also be used to align a block on left.

Example: Given an array of integers $A (a_i \geq 0, i \in [0, n])$

Code: Given an array of integers $A (a\_i \geq 0, i \in [0, n])$

Displayed Math

Use $$ $$ or \[ \] as delimiters for inline math, and wrap the section by <div> </div>

Example:

Code:

1
2
3
4
5
6
7
8

<div>
$$
F_0=0 \quad F_1=1 \\
and \\
F_n=F_{n-1}+F_{n-2} \\
for \quad n > 1
$$
</div>

Useful Links

• $\KaTeX$ Supported Functions