Render Math in Astro Markdown Pages with Katex

If you want to render math on your Astro website using $K A T E X$ but don’t know how, you’ve landed on the right blog post to learn how to do so. Enough with the introduction, let’s get down to business.

📦 Step 1: Package installation

You first are going to need to install the npm packages remark-math and rehype-katex.

$ npm install remark-math rehype-katex

If you’ve never heard of the remark library, it simply is a “tool that transforms markdown with plugins”, of which remark-math is one. What this particular plugin does is identify math within single and double dollar signs. It then hands it off to rehype-katex which produces the expected HTML code with the right tags and class names.

⚙️ Step 2: Modifying the Astro config file

To enable the remark and rehype plugins, you have to add them in the Astro config file astro.config.ts or astro.config.mjs. A minimal example of what it should look like for a ts file is given below.

import { defineConfig } from 'astro/config';

export default defineConfig({
    markdown: {
        remarkPlugins: [
            'remark-math',
        ],
        rehypePlugins: [
            ['rehype-katex', {
            // Katex plugin options
            }]
        ]
    }
});

🔗 Step 3: Adding the KaTex stylesheet

The penultimate step is adding the $K A T E X$ stylesheet in the head tag of your Astro layout file for Markdown pages. If you don’t already have one, you can easily create one in ./src/layouts/MarkdownLayout.astro that should look similar to the snippet below.

<html lang='en'>
    <head>
        <!-- Katex -->
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css"
            integrity="sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ" crossorigin="anonymous">
    </head>

    <body>
        <slot />
    </body>
</html>

The important part is having the $K A T E X$ stylesheet in the head tag and the <slot /> tag which your Markdown will replace.

💰 Step 4: Profit

Finally, in your Markdown files, all you have to do is set the layout property in the front matter to the Markdown layout file you created. For those who don’t know, the front matter is simply the section at the top of Markdown files enclosed by triple-dashed lines. The top of your Markdown files should therefore look something like this:

---
layout: 'path/to/MarkdownLayout.astro'
---

🎁 Bonus: Macros

Those that have written $L A T E X$ before know how convenient it is to use commands. They allow one, for example, to type out \R instead of \mathbb{R} to typeset the real numbers symbol. KaTex has something similar to it called macros which you can define in the options object of the rehype-katex plugin. Here are KaTex macros I currently have.

{
    // ... other Katex Options
    macros: {
        '\\E': '\\mathbb{E}',
        '\\C': '\\mathbb{C}',
        '\\R': '\\mathbb{R}',
        '\\N': '\\mathbb{N}',
        '\\Q': '\\mathbb{Q}',
        '\\bigO': '\\mathcal{O}',
        '\\abs': '|#1|',
        '\\set': '\\{ #1 \\}',
        '\\indep': "{\\perp\\mkern-9.5mu\\perp}",
        '\\nindep': "{\\not\\!\\perp\\!\\!\\!\\perp}",
        "\\latex": "\\LaTeX",
        "\\katex": "\\KaTeX",
    },
}

This humble set of macros shortens the real, complex, natural and rational number symbols to just a backslash followed by their respective letter symbols. Obviously, it’s in no way exhaustive and if you want to add new ones to your own configuration file, go head - only the stars are the limit.