Render LaTeX with KaTex in Hugo Blog
Authored by Edwin Kofler
Published on 2018-8-6
This method will NO LONGER WORK on recent version of Hugo. I recommend reading this post for up-to-date instructions.
Just recently, I added support to render LaTeX math equations with the rendering engine KaTeX for this blog. I chose it over MathJax because it performs substantially faster. To integrate KaTeX in my Hugo blog, I used the Mmark Markdown processor rather than Hugo’s default Blackfriday processor.
There are three steps to follow so you can write LaTeX in markdown for KaTeX to use.
- Create a KateX partial
- Integrate the KateX partial in your header or footer element
- Activate the KaTeX partial in the markdown file
What is a partial?
Hugo partials are just single page templates. Think of them like html
files that you can insert into any of your pages.
Create a KaTex partial
To get KaTex to work, you must import their JavaScript and CSS files. We’re going to do this using Hugo partials. To do this, create a katex.html
partial in your layouts/partials
directory of your Hugo project. In this file, just import the required files.
<!-- CSS File -->
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/dist/katex.min.css"
integrity="sha384-D+9gmBxUQogRLqvARvNLmA9hS2x//eK1FhVb9PiU86gmcrBrJAQT8okdJ4LMp2uv"
crossorigin="anonymous"
/>
<!-- JS File -->
<script
defer
src="https://cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/dist/katex.min.js"
integrity="sha384-483A6DwYfKeDa0Q52fJmxFXkcPCFfnXMoXblOkJ4JcA8zATN6Tm78UNL72AKk+0O"
crossorigin="anonymous"
></script>
Integrating the KaTeX partial
After creating the katex.html
partial file, now you have to include it in some element that is common in all your built site files, such as a header or footer element.
I’m going to add it in my footer partial. So, create a footer.html
partial in your layouts/partials
directory, if you don’t have one already. Since I have a theme, I copied the theme’s footer.html
partial and pasted it into my own footer.html
partial. Note that your footer.html
partial will override the theme’s.
Then, add the following to the footer.html
partial, outside of the body tag, but inside the html tag.
{{ if .Params.katex}}{{ partial "katex.html" . }}{{ end }}
My entire footer.html
file ended up looking like the following.
<footer class="footer">
<!-- Footer contents hidden for brevity -->
</footer>
</div>
</body>
{{ if .Params.katex}}{{ partial "katex.html" . }}{{ end }}
</html>
Everything else except that one line was copied and pasted from my theme’s footer.html
file.
By adding the katex.html
partial to the footer.html
partial conditionally, now you can specify if you want to use KaTex for each markdown file separately. That way, you don’t have to serve KaTeX JS and CSS files for blog posts that don’t actually use them.
Using the KaTex partial
Now, using the KaTex partial is trivial. In your Hugo front matter (of any markdown file), add the following lines.
---
katex: true
markup: 'mmark'
---
Now, your katex.html
partial will be used, which allows KaTex to render your LaTeX. Additionally, this activates the Mmark parsing engine, which is already integrated with Hugo. Using the Mmark parsing engine prevents the problems the default Blackfriday parsing engine has with parsing LaTex in markdown.
Writing LaTex in Markdown for Mmark
Now you can write LaTex in markdown files! 🎉 It’s intuitive writing LateX in markdown using the Mmark processor. You can display equations on the block level or inline. Note that you must use Mmark, or this will not work. Using the default Blackfriday processor will make all of these inline (using a single dollar sign as a delimiter will not work).
Display Block
Type equation on a single line, with top and bottom spaces. Use double dollar signs as delimiter.
The following
$$\int_{a}^{b} x^2 dx$$
Is an integral
The following
$$\int_{a}^{b} x^2 dx$$
Is an integral
Display Inline
Type the equation as per usual, nothing extra needed. Use double dollar signs as delimiter.
Integrate $$\int x^3 dx$$
Integrate $$\int x^3 dx$$
It turns out, using KaTeX rather than MathJax was easier than I thought. I hope you found this helpful 😄