Use mathematical formula with zola

I would like to use mathematical formula in one of my blog post. Is it possible to write it with zola ?


You will need to use a JS library for it, there are no math extensions in CommonMark. See that uses Katex

1 Like

@Grelot I created a simple theme using Katex to render math. You can take inspiration from it.

Hi everyone,

Thanks a lot, I will try one of these solutions soon and give you my feedback.

Have a good day :wink:

1 Like

So I’ve actually looked into this a bit and I have a proposal. As far as I understand at the moment the KaTeX rendering happens client-side (the site is static after all). However, KaTeX also enables server-side rendering, and there is even a rust library for it: Katex-rs which doesn’t need anything other than the crate as far as I understand. The case is pretty small, so it seems like this might be something that could be incorporated into the site generation fairly easily?

I get that this would be by no means a priority thing, but I do think it would be cool and also in the spirit of static site generators? I might pick this up myself, but I wanted to check and see if people would be on board with the idea :slight_smile:


I used mathjax rendering here:

mathjax is more powerful than katex but 20-30 times slower, which creates a delay of about 400ms

Katex still does not support some features I want, and mathjax is so slow.

So I also want to find a solution for server-side rendering, and the mathematical formula also should be static html.

1 Like

Definitely yes ! It would be better to render formula once and serve it as svg or png files.

I’ve tried to get this working, and while the code seems to be really quite simple, trying to compile both Katex-rs and Tera in the same project causes a linking error and I do not know enough about things under the hood to fix that. I suspect it has to do with I don’t know of other server-side LaTeX rendering that don’t require building an entire document so sadly for the time being this will not be possible.

@svente, can you share your config (OS/zola version/katex version) and test process if possible? I would like to give this a shot as well but having a basic idea of where to start and what issues you had would help me a lot.

Kris with a K

Of course, I hope you’ll be more sucessful than me! I don’t have the files anymore but I’ll work on reproducing one of these days. Stay Tuned!

Thanks Svente. I haven’t given it a shot yet because from your description, it sounds kind of thorny.

Fortunately the issue you linked that you suspected might be fixed now! There was a merge on an upstream dependency that may have fixed it. Edit; merge has not been passed on to yet.

Server-side KaTeX is the one feature that’s holding me back form using zola¹. I was going to open a pull request, fortunately I checked here first! The upstream bug was fixed in the merge request, but it’s not on yet because there has not been a new release, so maybe it’s worth asking them to add a new minor release, and then the development can be resumed?

¹ I was using jekyll-katex before, and I know there are some people who’ve set up a custom Makefile to get server-side KaTeX with Hugo.

1 Like

Would love it if the stars aligned.

Right now I am using client side katex rendering and happy enough with it. Zola is really flexible, you could easily start migrating now and be ready to use server side katex when its lined up!

I don’t have any javascript at all in my current website, and I really should take your advice and switch, since my current build system is totally borked and I’ve got so many version conflict errors that I cannot figure out how to fix it (I don’t like the gem package system or the npm package system). But I really don’t want to have any javascript at all ever… I might ask them to make a new release to and then try and implement it myself.

1 Like

Hi folks, sorry for the radio silence, I got tangled up in some other stuff. I’ll try to give it another whirl these days and also try to get a minimum working example going so other people can take a crack at it if they want.

One thing that is worth discussing though is how to handle configuration? For the moment I’ll just work on stock inline katex to get it all going, but down the line we’ll probably want to add options for configurations of some sort. Should those live in config.toml or in the templates? How much do we need to try an support? what do you all think?

The pull request into quickjs-rs has been released in version 0.3.2 and later on crates .io

If this was my problem …

![SVG of a Formula](formula.svg)

seems to work well enough in Zola (not so much in Discourse) with collocated assets, so all that is needed is a command line tool (e.g. tex2svg) to generate the SVG files into the appropriate folders within the content or static tree where they can be picked up by standard markdown as images.

That way no one is tied to any one particular (potentially in some way inadequate) implementation of (la)tex and Zola can focus on standard markdown features.

I agree that that would be a good solution, however Zola has “zero dependencies” as an explicit goal and this would go against that so I think that solution is unlikely to be merged.

Zola wouldn’t be affected in any way.

Zola can already include SVG files as images. I wouldn’t expect Zola to trigger the SVG generation process. I was thinking of running a (bash) script independent from Zola whenever the equations are updated, so that Zola can pick up the updated SVGs on the next generation pass.

There is nothing about equation/math support in the CommonMark Spec so the only other avenue would be processing via a shortcode.

I don’t think “zero dependencies” is supposed to imply “kitchen sink” functionality either. The nice thing about command line tools is how easily they can be composed with other command line tools.

Pull request to add KaTeX