Successfully Using LaTeX to Render Mathematical Formulas in Hugo

When building a blog or website with Hugo, we often need to insert mathematical formulas into articles. However, by default, Hugo cannot directly render these mathematical formulas. Previously, there were many solutions available online, but recently, starting from Hugo v0.122.0, official support for mathematical formulas has been introduced. With some configuration and steps, we can successfully achieve LaTeX mathematical formula rendering in Hugo. For official documentation, you can refer to Hugo Mathematics.

Step 1: Check and Update Hugo Version

First, we need to ensure that we are using Hugo v0.122.0 or higher. You can check your current Hugo version with the following command:

1

hugo version

If your Hugo version is lower than v0.122.0, you need to update Hugo. You can update via Homebrew (for macOS):

1
2


brew update
brew upgrade hugo

Or download the latest version of Hugo from the Hugo Releases page.

Step 2: Configure Goldmark Passthrough Extension

Enable the Goldmark passthrough extension in your site configuration file config.toml to preserve raw Markdown with mathematical formulas. You only need to add or modify the following content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


[params]
  math = true  # Ensure the math parameter is true to enable mathematical formula rendering

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true
        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['\[', '\]'], ['$$', '$$']]
          inline = [['\(', '\)']]

Step 3: Create `math.html` File in the Theme’s `layouts/partials/` Directory

Create a math.html file in your theme directory (e.g., themes/hugo-theme-stack/layouts/partials/) and add the following content to load MathJax:

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>

Step 4: Conditionally Call the Partial Template in the Base Template

Edit your base template layouts/_default/baseof.html (in your theme directory, e.g., themes/hugo-theme-stack/layouts/_default/baseof.html) to load mathematical formula support when needed. Add the following content:

1
2
3
4
5
6
7


<head>
  ...
  {{ if .Param "math" }}
    {{ partialCached "math.html" . }}
  {{ end }}
  ...
</head>

Step 5: Include Mathematical Formulas in Markdown Files

Use LaTeX or TeX syntax to add mathematical formulas in your Markdown files. For example:

 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
27
28


+++
date = 2024-01-24T18:09:49-08:00
title = 'Math examples'
[params]
  math = true
+++

This is an inline \(a^*=x-b^*\) equation.

These are block equations:

\[a^*=x-b^*\]

\[ a^*=x-b^* \]

\[
a^*=x-b^*
\]

These are block equations using alternate delimiters:

$$a^*=x-b^*$$

$$ a^*=x-b^* $$

$$
a^*=x-b^*
$$

By following the above steps, you can successfully render LaTeX mathematical formulas on your Hugo site.