Fixing Math Typesetting for the Hugo themes using config.toml (config.yaml)
I was setting up my static website a couple of weeks back and was switching themes, and along the process I messed up my Math Typesetting. Because my website is primarily focused on delivering math content, I needed to fix the issues right away.
Now, I use $ KaTeX $ math rendering engine to render math content in my blog posts. I did some research in the past and found out the katex’s rengering engine is faster than others. Like lightening fast!
I followed the suggestions provided under the katex.org website’s KaTeX Autorender page, and tried setting up as best I could.
-
Including the CDN in your script files. Done!
-
Adding partials under layouts/partials/ directory. Done!
-
Adding below line under
[params]section in the config.toml (or the congif.yaml) file. Done!math = true -
Adding
math = trueto the front matter of your blog posts. Done! -
What’s left? I’m still not seeing the math on my posts. 😢
Doing all of these steps, yet failing to render math setting in my posts, got me thinking that I’m not doing this right!
I did search on the internet, found couple of blog posts, but none of them helped me in solving my issues.
Later, I figured taking a closer look at the config.toml file contents might be helpful. This file holds all the key information. I realized the [params.csp] sections is where all the javascript contents are controlled. If you want to implement a Content-Security-Policy, add the params.csp section to the config file. It is really a nice way to block cross site scripting and other unknown scripts trying to access your page assets. Because the katex.org rendering engine has to run their javascripts on your blog posts, disabling cross scite scripts under [params.csp] could be our solution. 👍
You can test this out in two ways
-
Commenting out the entire
[params.csp]section. This is for quick check. This worked! -
Figuring out the domain name of the katex.org rendering engine and adding it to the parameters under the
[params.csp]section. This is an elegant way of doing it and is more like a permanent fix.
Heading over to the katex.org and looking at the autorendering scripts tells me that their content delivery network is cdn.jsdelivr.net and that is where they are getting their javascripts. You can download the javascripts and host them yourself. But for this article, we’ll just consdier the cross site scripts.
Which means, adding this domain name to the [params.csp] section should solve the issue.
Final Solution
Adding the domain to the scriptsrc parameter under the csp section.
Here’s how it was before.
scriptsrc = ["'self'", "'unsafe-inline'", "https://www.google-analytics.com"]
Here’s how it was after making the changes.
scriptsrc = ["'self'",
"'unsafe-inline'",
"https://www.google-analytics.com",
"https://cdn.jsdelivr.net/"]
Now, save the file, restart the server and you should be good to go!
Here are couple of examples on how the katex scripts render the math typesetting. The entire list of supported math functions using Tex functions are available here. KaTeX supported TeX functions
You can also download a pdf from here. Download LATEX Cheatsheet
Inline Math
Below line should give you a proper inline math setting. You encode (wrap) your math text with a single dollar symbol $.
$ \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\) $
$ (\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…) $
This text is also with the inline math setting.
$ \sum_{n=1}^{\infty} 2^{-n} = 1 $
$ \sum_{n=1}^{\infty} 2^{-n} = 1 $
Block Math
For block math coding, you encode (wrap) your math text with double dollar symbols $$. The difference is that the block math settings really help wrap multi-line math settings nicely. It also does the auto center alignment for you!
$$ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } $$
$$ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } $$
$$ \mu'=\frac{r^2\mu+\sigma^2\nu}{r^2+\sigma^2} $$
$$ \mu’=\frac{r^2\mu+\sigma^2\nu}{r^2+\sigma^2} $$
$$ \int_{a}^{b} x^2 dx $$
$$ \int_{a}^{b} x^2 dx $$
Adios! 😄