One of the challenges I encountered when moving my website from Jekyll to Docusaurus was rendering math equations in some of my blog posts (for example, about the apriori algorithm). In Jekyll, I used MathJax with Liquid to render them. This didn’t work in Docusaurus, so instead I had to use KaTeX.

The Docusaurus docs provide pretty clear instructions on how to use KaTeX in your project. This post is a more straightforward tutorial, and reflects my experience (and issues) specific to my website.

  1. Install the remark-math and rehype-katex plugins (in my case, with npm):

    npm install --save remark-math@3 rehype-katex@5 hast-util-is-element@1.1.0

  2. Open your project’s configuration file docusaurus.config.js:

    • At the top (right after the lines importing the Docusaurus themes), add the two plugins:

         const math = require('remark-math');
         const katex = require('rehype-katex');
    • In presets, under both the docs and blog categories, add the two plugins:

        remarkPlugins: [math],
        rehypePlugins: [katex],

      Make sure to add the plugins under all page categories where you want math equations to be rendered. I initially added them only under docs, and was confused why equations were rendered on my About page, but not in blog posts, until I figured out the reason.

    • In stylesheets, add the source of KaTeX:

          stylesheets: [
            href: '',
            type: 'text/css',
            crossorigin: 'anonymous',
  3. Update the formulas in existing content, considering the differences between Jekyll vs. Docusaurus, and MathJax vs. KaTeX.

    • In Jekyll, formulas are wrapped in double $$, whereas for Docusaurus they’re wrapped in single $. Replace all instances of $$ with $.
    • If some equations are still not displayed correctly, it might be because they need a different syntax in KaTeX than in MathJax. Check this in the KaTeX docs of suported functions and test the equations in their online editor.