Skip to main content

KaTeX Setup in Docusaurus

Official Documentation Method​

Applying maths equations via KaTeX\KaTeX is supported in Docusaurus. The setup steps, which involve importing the MDX plugins remark-math and rehype-katex, are documented here.

Note that the version of KaTeX\KaTeX as in the Docusaurus documentation is outdated (as of writing this note the latest version is 16.11), so you may need to refer to its CDN page to edit the version number and its integrity accordingly.

Client-side Rendering Method​

info

This method is adapted from this blog post by Mebiusbox.

According to Mebiusbox's blog post linked above, while the setup process described in the official documentation, which utilises server-side rendering, is fairly straightforward, it can take up more resources than needed, especially when a lot of LaTeX\LaTeX needs to be rendered.

More importantly (to me personally), the auto-render extension of KaTeX\KaTeX is not supported out of the box by remark-math and rehype-katex, causing custom or more 'LaTeX\LaTeX-friendly' delimiters like \( \) and \[ \] unable to be used.

Hence, this method, which involves client-side rendering, seeks to address this issue. Note that this method involves making a new Docusaurus plugin which acts as a replacement of remark-math and rehype-katex.

1. Include Required Scripts in Docusaurus Config​

First of all, let's import the required JavaScript and CSS files of KaTeX\KaTeX to load by including them in the scripts and stylesheets field of the config file respectively. Here, the latest version as of writing this article, i.e. 0.16.11, will be used.

Here are the JSDelivr links included:

If there is a change in version, the integrity for each of the files will need to be updated accordingly.

docusaurus.config.ts
const config: Config = {
    // ...
    scripts: [
    {
      src: "https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js",
      integrity: "sha384-7zkQWkzuo3B5mTepMUcHkMB5jZaolc2xDwL6VFqjFALcbeS9Ggm/Yr2r3Dy4lfFg",
      crossorigin: "anonymous",
      defer: true,
    },
    {
      src: "https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js",
      integrity: "sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk",
      crossorigin: "anonymous",
      defer: true,
    }
  ],
    // ...
  stylesheets: [
    {
      href: 'https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css',
      type: 'text/css',
      integrity: 'sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+',
      crossorigin: 'anonymous',
    },
  ],
    // ...
}

2. Create an Equation Rendering Plugin​

To apply the renderMathInElement function so that the KaTeX\KaTeX in your Docusaurus site can be rendered (with customised delimiters), we can create a Docusaurus plugin to achieve this. We'll follow the naming convention as in Mebiusbox's post and call the plugin docusaurus-plugin-katex-client (shortened as katex-client hereafter for simplicity).

From the home directory of your site folder, we first create the directory ./plugins/docusaurus-plugin-katex-client, containing the JavaScript files index.js and render.js.

└─ plugins
    └─ docusaurus-plugins-katex-client
        ├─ index.js
        └─ render.js

The index.js file will serve as a gateway to declare a client module that calls the renderMathInElement function. The code for index.js is as follows:

./plugins/docusaurus-plugin-katex-client/index.js
const path = require("path");
module.exports = function (context, options) {
  return {
    name: 'docusaurus-plugin-katex-client',
    getClientModules() {
      return [path.resolve(__dirname, "./render.js")];
    },
  };
};

As for the render.js file, the code will involve the use of the ExecutionEnvironment namespace (specifically its canUseDOM value), as well as onRouteDidUpdate, a client module lifecycle function. This will also be where the renderMathInElement function is called. The code for render.js is as follows:

./plugins/docusaurus-plugin-katex-client/render.js
import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";

export default (function () {
  if (!ExecutionEnvironment.canUseDOM) {
    return null;
  }

  return {
    onRouteDidUpdate({ location }) {

      const pathIsIncluded = 
        location.pathname.startsWith("/docs") ||
        location.pathname.startsWith("/blog");
      if (pathIsIncluded == false) {
        
        return null;
      }

      renderMathInElement(document.body, {
        delimiters: [
            {left: '$$', right: '$$', display: true},
            {left: '$', right: '$', display: false},
            {left: '\\(', right: '\\)', display: false},
            {left: '\\[', right: '\\]', display: true}
        ],
        throwOnError : false,
        strict: false
      }); 
    },
  };
})();

Note that the delimiters value can be customised based on your needs, or not specified at all (in this case, the default value will be applied instead).

3. Activate the Plugin​

Finally, to activate the plugin we've just created, we include the plugins field in the config file of the site.

docusaurus.config.ts
const config: Config = {
    // ...
    plugins: [
        './plugins/docusaurus-plugin-katex-client',
    ],
    // ...
}

Note that if you have set up KaTeX\KaTeX using the official documentation method previously, you will need to remove the import, remarkPlugins and rehypePlugins codes you've added in the config file before.

This then marks the completion of this setup method, and KaTeX\KaTeX equations should be normally rendered, with the use of custom delimiters enabled.

warning

While this method enables the support of the auto-render extension, there are some limitations that arise from it, as listed in the original blog post:

  • Client-side rendering means that the load time for equation rendering will be longer.
  • Escape characters are required when including LaTeX\LaTeX syntax in Markdown.
  • This method cannot be used with remark-math plus rehype-katex (or rehype-mathjax) applied alongside.
  • Some mathematical equations may fail to render after a page reloads.