2026-03-03
Hey, check this out:
\[ \Phi(x) = \frac{1}{\sqrt{2 \pi}} \int_{-\infty}^x e^{-\frac{t^2}{2}} \]
I just got LaTeX rendering on here! I guess that's a standard normal blog feature?
I'm using KaTeX, a Javascript library for rendering LaTeX math formulas to websites. Specifically, I'm using client-side rendering, where I send the formula \\(1 + 1\\) to your browser, and it runs the KaTeX code to create \(1 + 1\). You can also use the $$ syntax, but I'm trying to move to the directional \[ or \( syntax.
Turns out, it's pretty easy to add KaTeX support to a website. You can just add the Javascript file and CSS to your HTML, referencing the CDN.
For a Markdown blog, you'd also want autorender support, which lets you write the typical LaTeX syntax in Markdown, i.e., $, $$, \(, and \[.
If you have a dialup internet connection, my pages might have gotten really hard to load all of a sudden! I've gone from a relatively small static HTML page to including thousands of lines of CSS and Javascript. While necessary for client-side LaTeX rendering, many of my notes don't involve any equations!
Fortunately for all those times you have a poor connection, I can only include KaTeX on the pages that actually need it. Overall, it's just two steps:
{% if page.extra.katex %} – {% endif %} block.katex = true to the [extra] block in the page's front matter (the "+++" block).+++
title = "Your title"
# The rest of your front matter
[extra]
katex = true
+++Now go check the source for this page and any older one. You'll see KaTeX included here, but not used on any of those earlier notes that didn't need it.
If you try this yourself, you'll notice that inline formulas, like \(1 + 1\), look a bit too big. Turns out, that sizing is intentional, and KaTeX specifically wants to use a font 21% larger than regular text. While the sizing looks a bit silly for something simple like \(1 + 1\), it helps readability when there's a lot of tiny superscripts or subscripts: \( X_i^2 \).
It's a matter of taste, and I prefer to have the formula sizes match my text sizes. You can change the sizing in your CSS.
.katex { font-size: 1rem; }Just remember to have this setting after you include the KaTeX CSS.
Try copying this formula:
\[ \Phi(x) = \frac{1}{\sqrt{2 \pi}} \int_{-\infty}^x e^{-\frac{t^2}{2}} \]
You should get back exactly the LaTeX that generates it:
$ \Phi(x) = \frac{1}{\sqrt{2 \pi}} \int_{-\infty}^x e^{-\frac{t^2}{2}} $You won't get this on base KaTeX however; copying the formula would give a collection of symbols that aren't really useful:
Φ(x)=
2π
1
∫
−∞
x
e
−
2
t
2
KaTeX provides the copy-tex extension, which substitutes in the LaTeX whenever you try to copy KaTeX in the browser. To enable this extension, you just need to include one more script along with the base KaTeX script and CSS.
So this is all great for formulas, but what if you need some \begin{}\end{} environment, like for an equation? You wouldn't use the equation delimiters in normal LaTeX, so the KaTeX we have so far won't help either.
KaTeX supports these blocks through <script type="math/tex"></script>. You'll need to add the math/tex extension, just like you added the autorender and copy extensions. This code will search for the math/tex scripts and render them.
At this point, we need to use Zola shortcodes, which are essentially custom functions or blocks that expand into HTML.
To create your KaTeX shortcode, create a katex.html in the templates/shortcodes directory.
<script type="math/tex mode=display">
{{ body | safe }}
</script>Since we want "display" (not inline) rendering, we need to have mode=display in the type somewhere. The script is pretty permissive, so you could do all sorts of things like mode = display, math/tex and still trigger the autorender.
Anyways, this shortcode has no arguments but uses body for the contents between the tags.
You can call it with
{% katex() %}
\begin{align}
y &= (x + 1)^2 \\
&= x^2 + 2x + 1
\end{align}
{% end %}This block will nicely render the multi-line equation!
You can also use shortcodes as a replacement for the delimiters. The current KaTeX setup reads through my text, finds the delimiters, and replaces the LaTeX code with a rendered formula. I prefer this way, since I can write nice Markdown for my notes.
The other way to use KaTeX would be to explicitly call it with a shortcode block each time. I find this a lot clunkier than using \\(1 + 1\\), but it's more general and customizable if you need something different. (If you want to go with only shortcodes, you'll want to modify the one above to allow inline rendering too.)
One last thing: KaTeX might not support everything you could do with LaTeX. Check out their supported functions if you're running into issues.