This blog should be a complete guide to render mathematics in Hugo. However, if you have problems reproducing this blog, note that the official documentation is always the best place to start:

  1. HUGO - Mathematics in Markdown
  2. Cloudfare - Use a Newer HUGO Verseion

First, add following code to hugo.yaml:

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

params:
  # ...
  math: true
  # ...

markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block:
          - - \[
            - \]
          - - $$
            - $$
          inline:
          - - \(
            - \)
          - - $
            - $
        enable: true

Second, create a new file layouts/partials/extend_head.html:

1
2
3

{{ if .Param "math" }}
  {{ partialCached "math.html" . }}
{{ end }}

Note that name and path of the created file is based on your theme configuration.

For example, in theme PaperMode (which I use), “extend_head.html” indicates that, to extend the head, I can create a file named extend_head.html in ./layouts/partials/ (so-called global layouts, without modifying layouts inside the theme).

In other words, if your theme does not support this feature, you may need to copy the head.html from the theme to global layouts and modify it, or simply modify the theme directly (but rememenber that modifications in git submodules will not be committed to the remote repository).

Next, create a new file layouts/partials/math.html:

1
2
3
4
5
6
7
8
9

<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
<script>
  MathJax = {
    tex: {
      displayMath: [['\\[', '\\]'], ['$$', '$$']],  // block
      inlineMath: [['\\(', '\\)'], ['$', '$']]      // inline
    }
  };
</script>

Now, you can render both block and inline mathematics in your content files. For example, the following code renders the equation $O=Attention(Q,K,V)=softmax(\frac{QK^T}{\sqrt{d_k}})V$:

1
2
3

$$
O=Attention(Q,K,V)=softmax(\frac{QK^T}{\sqrt{d_k}})V
$$

Test it locally by running hugo server -D . to see if the equation rendered correctly.

Finally, there is one more thing to note before deploying your website.

You should always use the newest version of hugo to support all features (in goldmark).

Why? In previous versions, the passthrough extension is not supported, and consequently, \\ inside the equation will be rendered as \ instead of a new line.

Based on the official doc, if you are using Cloudflare to deploy your website:

  1. Go to Workers & Pages -> Your Porject -> Settings -> Variables and Secrets;
  2. Add a new variable HUGO_VERSION with value 0.135.0 at least.

This will specify the version of Hugo used by Cloudflare to build your website.