John Dalesandro

How to Add Math Equations to Astro with KaTeX

Published

By John Dalesandro

If you write technical, scientific, or data-focused content, you will eventually need to display mathematical equations. Plain text is not enough for formulas, symbols, and structured expressions.

Astro makes this easy with KaTeX, a fast and lightweight LaTeX renderer that works well with static sites. With a simple setup, you can render professional-looking equations directly in your Markdown files.

In this guide, you will learn how to:

By the end, you will be able to add clean, readable math to your site without adding unnecessary JavaScript or slowing down your pages.

Why Use KaTeX with Astro?

KaTeX is a popular tool for rendering math on the web because it is:

When combined with Astro’s Markdown system, KaTeX renders equations at build time. This keeps your pages fast, accessible, and SEO-friendly. I use it on this site to explain the equations behind my Treasury Bill Yield Calculator.

Instructions

Step 1: Install Math Rendering Plugins

You only need to install two packages to enable math rendering in Astro:

KaTeX is included automatically as a dependency, so no separate installation is required.

Install both packages:

npm install remark-math rehype-katex

Step 2: Configure Astro for Math Support

Next, open your Astro configuration file (astro.config.mjs) and update it as follows:

import { defineConfig } from 'astro/config';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

This configuration tells Astro to:

After this step, Astro can process equations automatically.

Step 3: Add KaTeX Styles

KaTeX requires CSS to display equations correctly. Without it, formulas will appear unstyled or broken.

There are several ways to load the styles, depending on how often your site uses math.

If you only use math in a few posts, importing CSS locally can reduce unnecessary page weight. If many pages use math, a global import may be more practical.

Option 1: Import in Markdown

If you only use math occasionally, import KaTeX in individual .mdx files:

import 'katex/dist/katex.min.css';

This loads the styles only where needed.

Option 2: Import in a Main Layout

You can also import KaTeX in a shared layout file:

---
import 'katex/dist/katex.min.css';
---

All pages using this layout will include the styles.

Option 3: Import in a Global CSS File

If your site uses global styles, add:

@import "katex/dist/katex.min.css";

All pages using this global stylesheet will include the KaTeX styles.

Step 4: Writing Math in Markdown

Once setup is complete, you can write math directly in Markdown files using LaTeX syntax.

Inline Math

Use single dollar signs for inline equations:

Mass-energy equivalence (Einstein’s formula) is $E = mc^2$.

Which renders as:

Mass-energy equivalence (Einstein’s formula) is E=mc2E = mc^2.

This renders the equation inside the sentence and keeps the text flowing naturally.

Block Math

Use double dollar signs for centered equations:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Which renders as:

∫0∞e−x2dx=π2\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}

Block math is best for longer or more complex formulas that require visual emphasis.

Summary

Adding KaTeX to an Astro site lets you display clean, professional math using simple Markdown syntax. The setup requires only two plugins and a CSS import, and all rendering happens at build time. Once configured, you can focus on writing content instead of formatting equations.