redstrate.com/content/blog/integrating-katex-and-threejs/index.md

title	date	draft	tags
Integrating KaTeX and Three.js into Hugo	2025-01-01	false	GLSL WebGL Math Hugo

One of my [Graphics Dump posts]({{< ref "drawing-simple-cubes" >}}) integrates three.js and KaTeX into the article itself, which was a first for me. I want to use these libraries in future posts, so I want it to be easy and reusable.

Note: I had written this setup in 2023, and now in modern Hugo there is built-in LaTeX support.

Three.js

If you aren't familiar, three.js is an easy to use WebGL framework/engine and does a lot of useful work out of the box. When you just want to display a mesh, or a primitive and slap some materials on it you can't really get anything better. However, it wasn't very straightforward to integrate it and I also want to use custom GLSL shaders that complicates things a bit.

I self-host my own JavaScript files, and the easiest way to grab a ready-to-use distribution of three.js is from the repository under the "build" directory. To enable three.js for a specific post, I enable it via a parameter in the frontmatter:

---
title: "Integrating KaTeX and Three.js into Hugo"
threejs: true
---

And then in single.html (or whatever layout you're using for posts) I check for the parameter and insert the JavaScript:

{{ if .Params.threejs }}
    {{ $threejs := resources.Get "js/three.js" }}
    {{ if hugo.IsProduction }}
        {{ $threejs = $threejs | minify | fingerprint | resources.PostProcess }}
    {{ end }}
    <script src="{{ $threejs.RelPermalink }}" integrity="{{ $threejs.Data.Integrity }}"></script>
{{ end }}

That's only half the battle, as we still need to set up the scene and the render loop. To do this, I put the JavaScript files in the page directory. Then using this shortcode I insert a three.js scene inline:

{{ $path := .Get 0 }}
{{ $id := .Get 1 }}
<div class="threejs-canvas" id="{{ $id }}"></div>
<script type="module" src="{{ $path }}"></script>

This adds a container and the script itself, and can be used as so:

{ {< three-scene "scene.js" "scene" >} }

("scene.js" is of course the script path, and "scene" is the name of the container.)

On the three.js side, we query for the container and add the canvas to it:

document.getElementById('scene').appendChild(renderer.domElement);

I add some CSS to the container to take up 50% of the article width, so we need some way to automatically tell three.js to resize as the canvas changes. First, add a ResizeObserver that calls a resize() function:

const resizeObserver = new ResizeObserver(resize);
resizeObserver.observe(renderer.domElement, {box: 'content-box'});

The resize function is as follows, which is updating the renderer size and the camera aspect ratio:

function resize() {
  const canvas = renderer.domElement;
  const width = canvas.clientWidth;
  const height = canvas.clientHeight;

  // you must pass false here or three.js sadly fights the browser
  renderer.setSize(width, height, false);
  camera.aspect = width / height;
  camera.updateProjectionMatrix();
}

Right now this has to be set up for each and every JavaScript file, but I should move it into a common file for all of them later down the road.

KaTeX

KaTeX is a LaTeX-compatible JavaScript math renderer, and so much easier to integrate than three.js. There's three files we need to include, katex.js, katex.css and auto-render.js (from the contrib folder).

Like with three.js, I have an explicit toggle to enable it in the front-matter:

---
title: "Integrating KaTeX and Three.js into Hugo"
math: true
---

And then I have this in my template:

{{ if .Params.math }}
    {{ $math := resources.Get "js/katex.js" }}
    {{ if hugo.IsProduction }}
        {{ $math = $math | minify | fingerprint | resources.PostProcess }}
    {{ end }}
    <script src="{{ $math.RelPermalink }}" integrity="{{ $math.Data.Integrity }}"></script>

    {{ $autorender := resources.Get "js/auto-render.js" }}
    {{ if hugo.IsProduction }}
        {{ $autorender = $autorender | minify | fingerprint | resources.PostProcess }}
    {{ end }}
    <script src="{{ $autorender.RelPermalink }}" integrity="{{ $autorender.Data.Integrity }}"></script>

    {{ $style := resources.Get "css/katex.css" }}
    {{ if hugo.IsProduction }}
        {{ $style = $style | minify | fingerprint | resources.PostProcess }}
    {{ end }}
    <link href="{{ $style.RelPermalink }}" integrity="{{ $style.Data.Integrity }}" rel="stylesheet">

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

The actual code itself is simple, and is just a <script> block waiting for the DOM to load. The rest of the snippet is all of the bits of KaTeX you need to actually use it.

Credits

• This StackOverflow answer explaining how to inform three.js about canvas resizes.
• "Math Typesetting in Hugo" for a guide on how to use KaTeX.