Adding Math Formula Support to Hugo

I happened to need it, so I just went ahead and solved it, based on KaTeX. It supports math formulas almost perfectly; both inline and display formulas can be rendered directly without modifying or adding any Shortcodes. The only drawback is that symbols with a double meaning in Markdown syntax itself, such as *, need to be escaped as \*.

Steps

1. Modify extend_head.html

All paths below are described with the site root directory as the current directory:

If layouts/partials/extend_head.html exists, simply append the content at the end; if it doesn’t exist, create that path and copy the specified file into the directory for editing. The command is as follows:

1
2

cp themes/PaperMod/layouts/partials/extend_head.html layouts/partials/extend_head.html \
  && nano layouts/partials/extend_head.html

Following the KaTeX documentation Auto-render Extension, add the following content:

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

{{ if or .Params.math .Site.Params.math }}
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
    integrity="sha384-bYdxxUwYipFNohQlHt0bjN/LCpueqWz13HufFEV1SUatKs1cm4L6fFgCi1jT643X" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js"
    integrity="sha384-Qsn9KnoKISj6dI8g7p1HBlNpVx0I8p1SvlwOldgi3IorMle61nQy4zEahWYtljaz"
    crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js"
    integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05"
    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 }}

2. Usage

Add the following field to the front matter of the article in which you want to use math formulas:

1

math: true # 是否开启mathjax

You can also add the above setting to archetypes/defaults.md, so that the field is automatically added every time a new article is created. In addition, changing true to false will disable the math formula feature in that article.

The usage format is the same as Markdown math formulas. Just be aware of the characters that need escaping. Here is an example, in which * is escaped as \*.

1

$$0.414213562373095048\approx6\*16^{-1}+a\*16^{-2}+0\*16^{-3}+\cdots$$

$$0.414213562373095048\approx6*16^{-1}+a*16^{-2}+0*16^{-3}+\cdots$$

References