Katex Math Rendering

Apart from using the method mentioned in [[math-support-with-mathjax]], 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 [[publish-to-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 [[publish-to-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 [[publish-to-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 %}{% endraw %}.
Or multiple math equations in paragraphs wrapped inside {% raw %}{% katexmm %} ... {% endkatexmm %}{% endraw %}.

In our case, we'll be using the latter tag to wrap our {% raw %}{{ content }}{% endraw %}. Wrap {% raw %}{{ content }}{% endraw %} 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.

Backlinks

Recipes

- adding a custom Jekyll plugin to support [[math-support-with-katex]]

Publish to Vercel

_If you want to use LaTeX rendered with KaTeX (which is what the plugin `jekyll-katex` does), you can specify it here. And yes, one of the benefits of deploying with Vercel is that we can use KaTeX to render LaTeX! More on: [[math-support-with-katex]]_

Publish to Vercel

Besides adding the plugin `jekyll-katex` in `_config.yml` and `Gemfile`, we'll also have to follow the guides in [[math-support-with-katex]] to let our site fully support using KaTeX to render math equations.