chore: server side rendering of math equations (#543)

Andreas Deininger

07.03.2025 52cb4b7a7029ec36389afab3b762728a6942d0b2

chore:  server side rendering of math equations (#543)

Co-authored-by: Alexander Bilz <mail@alexbilz.com>

 exampleSite/config/_default/hugo.toml

@@ -24,8 +24,14 @@

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

[taxonomies]
    category = "categories"

 exampleSite/config/_default/params.toml

@@ -56,11 +56,6 @@
# id = "94db1cb1-74f4-4a40-ad6c-962362670409"
# trackerScriptName = "mycustomscriptname.js"

## Math settings
[math]
enable = false  # options: true, false. Enable math support globally, default: false. You can always enable math on per page.
use = "katex"  # options: "katex", "mathjax". default is "katex".

## Social links
# use 'fa-brands' when brand icons, use 'fas' when standard solid icons.
[[socialIcons]]

 exampleSite/content/english/post/math-typesetting.md

@@ -1,48 +1,44 @@
---
author: Hugo Authors
title: Math Typesetting
date: 2019-03-08
description: A brief guide to setup KaTeX
math: true
date: 2025-02-23
description: A brief guide to setup and use KaTeX
---

Mathematical notation in a Hugo project can be enabled by using third party JavaScript libraries.

For math typesetting in a Hugo project, you can leverage hugo's internal [\(\KaTeX\)](https://katex.org/) rendering engine.
<!--more-->

In this example we will be using [KaTeX](https://katex.org/)
If you want to use mathematical or chemical equations in your site, enable the [Goldmark passthrough extension](https://gohugo.io/render-hooks/passthrough/) and define delimiters for block and inline formulae in your config file:

- Create a partial under `/layouts/partials/math.html`
- Within this partial reference the [Auto-render Extension](https://katex.org/docs/autorender.html) or host these scripts locally.
- Include the partial in your templates like so:
**`hugo.toml`**

```bash
{{ if or .Params.math .Site.Params.math }}
{{ partial "math.html" . }}
{{ end }}
```toml
[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true
        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['\[', '\]'], ['$$', '$$']]
          inline = [['\(', '\)']]
```

- To enable KaTex globally set the parameter `math` to `true` in a project's configuration
- To enable KaTex on a per page basis include the parameter `math: true` in content files

**Note:** Use the online reference of [Supported TeX Functions](https://katex.org/docs/supported.html)

{{< math.inline >}}
{{ if or .Page.Params.math .Site.Params.math }}

<!-- KaTeX -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.js" integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>
{{ end }}
{{</ math.inline >}}
Afterwards you can author formulae using the standard \(\LaTeX\) syntax:

### Examples

Inline math: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
Inline math: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887… \)

Block math:

$$
 \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
\tag*{(1)} \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots}}} 
$$

Chemical equations:

\[
\tag*{(2)} \ce{Zn^2+  <=>[+ 2OH-][+ 2H+]  $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$  <=>[+ 2OH-][+ 2H+]  $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$}
\]

**Note:** Use the online reference of [Supported TeX Functions](https://katex.org/docs/supported.html)

 layouts/_default/_markup/render-passthrough.html

New file
@@ -0,0 +1,9 @@
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with try (transform.ToMath .Inner $opts) }}
  {{- with .Err }}
    {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
  {{- else }}
    {{- .Value }}
    {{- $.Page.Store.Set "hasMath" true }}
  {{- end }}
{{- end -}}

 layouts/partials/footer.html

@@ -26,7 +26,6 @@
  </ul>
</footer>
{{- partial "medium-zoom.html" .context -}}
{{- partial "math.html" .context -}}
{{- if (hasPrefix .context.Site.Config.Services.GoogleAnalytics.ID "G-") -}}
  {{- template "_internal/google_analytics.html" .context -}}
{{- end -}}

 layouts/partials/head.html

@@ -230,4 +230,20 @@

  <!-- Schema.org-->
  {{ partial "schema.html" . }}

  <!-- KaTeX-->
  {{ $noop := .WordCount }}
  {{ if .Page.Store.Get "hasMath" }}
    {{ $katex_css_url := printf "https://cdn.jsdelivr.net/npm/katex@latest/dist/katex%s.css" (cond hugo.IsProduction ".min" "") -}}
    {{ with try (resources.GetRemote $katex_css_url) -}}
      {{ with .Err -}}
        {{ errorf "Could not retrieve KaTeX css file from CDN. Reason: %s." . -}}
      {{ else with.Value -}}
        {{ with resources.Copy (printf "css/katex%s.css" (cond hugo.IsProduction ".min" "")) . }}
          {{ $secureCSS := . | resources.Fingerprint "sha512" -}}
<link rel="stylesheet" href="{{- .RelPermalink -}}" integrity="{{- $secureCSS.Data.Integrity -}}" crossorigin="anonymous">
        {{ end -}}
      {{ end -}}
    {{ end -}}
  {{ end }}
</head>

 layouts/partials/math.html

File was deleted