Skip to content

Katex Math Rendering#

Apart from using the method mentioned in math-support, we can also use KaTeX to render our math equations in Foam. The caveat is: we can't rely on GitHub Pages to host and deploy our website anymore, because the plugin we'll be using to let Jekyll support KaTeX doesn't play well together with GitHub Pages.

The alternative solution is to using vercel for building and publishing our website, so before you start integrating KaTeX into your Foam project, please follow the instructions to host your Foam workspace on vercel first.

Adding required plugins#

Add the plugin jekyll-katex to your Foam workspace's _config.yml and Gemfile if you haven't done so already. For detailed instructions, please refer to the #Adding a _config.yml and #Adding a Gemfile in vercel.

Loading KaTeX JS and CSS#

Because we are using KaTeX to render math, we will also need to import KaTeX's JS and CSS files from CDN. The official method to load these files is documented at: KaTeX/KaTeX#starter-template. In our case, we will need to add the following code snippet to our _layouts/page.html:

<!-- _layouts/page.html -->
---
layout: default
---

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">

<!-- The loading of KaTeX is deferred to speed up page rendering -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>

<!-- To automatically render math in text elements, include the auto-render extension: -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>

<!-- ... -->

Adding liquid tags to wrap page content#

The plugin jekyll-katex focuses on rendering:

  • Single math equations wrapped inside katex liquid tags like {% raw %}{% katex %} ... {% endkatex %}.
  • Or multiple math equations in paragraphs wrapped inside {% raw %}{% katexmm %} ... {% endkatexmm %}.

In our case, we'll be using the latter tag to wrap our {% raw %}{{ content }}. Wrap {% raw %}{{ content }} in the liquid tags inside _layouts/page.html like so:

<!-- _layouts/page.html -->

<!-- ... -->
{% raw %}{% katexmm %} {{ content }} {% endkatexmm %}{% endraw %}
<!-- ... -->

Render equations in Foam's homepage as well#

You may have noticed that we only made modifications to the template _layouts/page.html, which means that _layouts/home.html won't have KaTeX support. If you wan't to render math in Foam's home page, you'll need to make the same modifications to _layouts/home.html as well.

Finally, if all goes well, then our site hosted on Vercel will support rendering math equations with KaTeX after commiting these changes to GitHub. Here's a demo of the default template with KaTeX support: Foam Template with KaTeX support.