Add katex support to Hugo

Recently I decide to post some math notes on the blog, so here is how to add math formula rendering support to hugo. Actually it’s as simple as adding several lines to Hugo’s theme file.

this link is my main reference but I need a little mod.

Katex by defaults uses double dollars $$ as delimiter no matter it is inline formular or block. However I want to use $ as inline delimiter and $$ for block, since besides Hugo I’m using a vim-markdown preview plugin, which uses different delimiter for inline and block rendering.

Here is how to do it.

0. Simpler approach

simply put the following lines into the header partial. In most Hugo themes it is theme/layouts/partials/header.html

1
2
3
4
5
6
7
8
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">

<!-- The loading of KaTeX is deferred to speed up page rendering -->
<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>

<!-- To automatically render math in text elements, include the auto-render extension: -->
<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>

before the </header> tag.

1. Smarter approach

We want to:

  • load katex and render page only when explicitly specified.
  • modify katex delimiter as mentioned before.

1.0 Add partials to hugo theme

Add a partial file to the theme, z.B. theme/layouts/partials/katex.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/katex.min.css">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/katex.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/contrib/auto-render.min.js"></script>

    <script>
      renderMathInElement(
          document.body,
          {
              delimiters: [
                  {left: "$$", right: "$$", display: true},
                  {left: "\\[", right: "\\]", display: true},
                  {left: "$", right: "$", display: false},
                  {left: "\\(", right: "\\)", display: false}
              ]
          }
      );
    </script>

1.1 Modify footer partial

Add the following lines in the footer partial (in most cases footer.html) right before the <\body> tag.

{{ if .Params.katex}}{{ partial "katex.html" . }}{{ end }}

This will load katex.html only when the katex parameter in the front matter is set to true. Then katex.html partial will call renderMathElement function to render the body.

Here is a testing markdown file

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
---
title: "katex_test"
date: 2020-05-28T21:22:48+02:00
katex: true
draft: false
---

this is an inline form .. $x^2 + y^2 = 1$

this is a block

$$\sum_{\mathclap{1\le i\le j\le n}} x_{ij}$$

1.2 Modify archetypes file

It works! Now we need to add katex and markup parameters to the front matter automatically when creating a new post file. simply modify site/archetypes/defult.md like:

1
2
3
4
5
6
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
katex: false
draft: true
---


[+] click to leave a comment [+]
the comment system on this blog works via email. The button
below will generate a mailto: link based on this page's url 
and invoke your email client - please edit the comment there!

[optional] even better, encrypt the email with my public key

- don't modify the subject field
- specify a nickname, otherwise your comment will be shown as   
  anonymous
- your email address will not be disclosed
- you agree that the comment is to be made public.
- to take down a comment, send the request via email.

>> SEND COMMENT <<




Fun with Image Maps and SVGs via benji February 20, 2024

Over the past few weeks I've been playing around with making some images on my website interactive. My "informatics" class in high school taught us some basic HTML. By basic I mean in notepad and writing everything by hand, saving to a...

Goblin Week 2024 via Helvetica Blanc January 26, 2024

It snuck up on me, but I managed to draw my little goblins to celebrate the week! I love my children - they're like awful Pikmin. I've uploaded the whole parade as a print, as well as individual prints for each goblin. There's something very fu…

How to trust gpg keys via Travis Shears Personal Site October 27, 2023

After moving some GPG keys to a new computer I kept getting these trust warnings. It is NOT certain that the key belongs to the person named in the user ID.If you * really * know what you are doing, you may answer the next question with yes. Use this key a…

Generated by openring from webring