underlap

Formatting maths in Eleventy with KaTeX

Today I noticed that some of the maths in a draft post (which happened to be in LaTeX) rendered correctly in preview. When I introduced a syntax error in the maths, preview failed with “KaTeX parse error”.

This led me to the KaTeX project and the markdown-it-katex plugin.

With a bit of debugging help (from vrugtehagel on the eleventy discord instance), it turned out I needed to do a couple of things to get the plugin working in eleventy:

  1. Override the dependency from markdown-it-katex to katex to v0.16.22.[1]
  2. Specify the output option 'mathml.

The updated portion of my package.json is:

"dependencies": {
    ...
    "markdown-it-katex": "^2.0.3"
},
"overrides": {
    "markdown-it-katex": {
        "katex": "0.16.22"
    }
}

and of my eleventy config is:

const katexOptions = {
    output: 'mathml'
};

const markdownLibrary = markdownIt({
    html: true,
    breaks: false,
    linkify: true,
    typographer: true
})
   .use(markdownItFootnote)
   .use(markdownItKatex, katexOptions);

eleventyConfig.setLibrary("md", markdownLibrary);

Just to prove the maths renders ok, here’s an example:[2]

⋃i∈NFi({}){\displaystyle \bigcup _{i\in \mathbb {N} }F^{i}(\{\})}

  1. The dependency was pretty old: v0.6.0. The new version was needed to recognise the “output” option. ↩︎

  2. This is from a draft post. The maths is taken from wikipedia. ↩︎