/posts/writing-math-equations-in-astro

Writing Mathematical Equations in Astro

A comprehensive guide to rendering beautiful math equations in Astro markdown files

Publication date: 2024-10-15

Updated: 2024-10-16

Mathematical equations written on a blackboard

Writing Mathematical Equations in Astro Markdown Files

As developers and technical writers, we often need to include mathematical equations in our documentation, blog posts, or educational content. In this tutorial, I’ll show you how to integrate mathematical equations into your Astro-powered website using popular math typesetting libraries.

This tutorial assumes you have a basic Astro project set up. If you're new to Astro, check out the official getting started guide first.

Why Add Math Equations to Your Astro Site?

Mathematical equations are essential for:

  • Technical documentation
  • Scientific articles
  • Educational content
  • Data science and machine learning explanations
  • Physics, engineering, and mathematics tutorials

Choosing a Math Rendering Library

There are two popular libraries for rendering mathematical equations on the web:

  1. KaTeX - Faster rendering, smaller bundle size, but supports fewer LaTeX commands
  2. MathJax - More comprehensive LaTeX support, but slightly larger and sometimes slower

For this tutorial, we’ll implement KaTeX as it’s lightweight and works well with Astro’s partial hydration model.

KaTeX is up to 100x faster than MathJax and doesn't need to reflow the page on load, making it ideal for static sites built with Astro.

Setting Up KaTeX in Your Astro Project

Step 1: Install KaTeX

First, let’s install KaTeX and its dependencies:

npm install katex
npm install rehype-katex remark-math

Step 2: Configure Astro to Use KaTeX

Update your astro.config.mjs file to include the KaTeX plugins:

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

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

Step 3: Add KaTeX CSS

You need to include the KaTeX CSS in your project. The easiest way is to add it to your main layout component. Open your layout file (e.g., BaseLayout.astro or MarkdownPostLayout.astro) and add:

---
// Your existing imports and frontmatter
---

<html lang="en">
  <head>
    <!-- Your existing head content -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css" 
          integrity="sha384-GvrOXuhMATgEsSwCs4smul74iXGOixntILdUW9XmUC6+HX0sLNAK3q71HotJqlAn" 
          crossorigin="anonymous">
  </head>
  <body>
    <!-- Your existing body content -->
    <slot />
  </body>
</html>
Always check for the latest version of KaTeX on the official KaTeX documentation to ensure you're using the most up-to-date and secure version.

Writing Math Equations in Markdown

Now that we have KaTeX set up, let’s look at how to write equations in your markdown files.

Inline Equations

For inline equations, use single dollar signs $:

The famous Einstein's equation $E = mc^2$ relates energy and mass.

This renders as: The famous Einstein’s equation $E = mc^2$ relates energy and mass.

Block Equations

For block equations (displayed on their own line), use double dollar signs $$:

Newton's second law of motion:

$$F = m \cdot a$$

Where $F$ is force, $m$ is mass, and $a$ is acceleration.

This renders as:

Newton’s second law of motion:

$$F = m \cdot a$$

Where $F$ is force, $m$ is mass, and $a$ is acceleration.

Advanced Equation Examples

Let’s explore some more complex equations to showcase KaTeX’s capabilities:

The Quadratic Formula

$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$

Renders as:

$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$

Maxwell’s Equations

$$\begin{aligned}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}} \\
\nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
\nabla \cdot \vec{\mathbf{B}} & = 0
\end{aligned}$$

Renders as:

$$\begin{aligned} \nabla \times \vec{\mathbf{B}} -, \frac1c, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}} \ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \ \nabla \times \vec{\mathbf{E}}, +, \frac1c, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \ \nabla \cdot \vec{\mathbf{B}} & = 0 \end{aligned}$$

Euler’s Identity

$$e^{i\pi} + 1 = 0$$

Renders as:

$$e^{i\pi} + 1 = 0$$

Using Math in Tables

You can also include equations in markdown tables:

| Equation | Description |
|----------|-------------|
| $E = mc^2$ | Einstein's mass-energy equivalence |
| $F = G\frac{m_1 m_2}{r^2}$ | Newton's law of universal gravitation |
| $\vec{F} = m\vec{a}$ | Newton's second law of motion |
EquationDescription
$E = mc^2$Einstein’s mass-energy equivalence
$F = G\frac{m_1 m_2}{r^2}$Newton’s law of universal gravitation
$\vec{F} = m\vec{a}$Newton’s second law of motion

Troubleshooting Common Issues

Equations Not Rendering

If your equations aren’t rendering correctly, check the following:

Make sure you've properly configured the remark-math and rehype-katex plugins in your astro.config.mjs file.
  1. Verify that the KaTeX CSS is properly loaded
  2. Check for syntax errors in your LaTeX equations
  3. Ensure there are no spaces between the dollar signs and your equation

Escaping Special Characters

Sometimes you need to use dollar signs as actual currency symbols, not as math delimiters. In these cases, you can escape the dollar sign with a backslash:

The product costs \$25, not $25 = 5^2$.

Alternative: Using MathJax

If you prefer MathJax over KaTeX, the setup is slightly different:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  // MathJax doesn't need special remark/rehype plugins
});

Then add the MathJax script to your layout:

<script>
  window.MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      displayMath: [['$$', '$$'], ['\\[', '\\]']],
    },
    svg: {
      fontCache: 'global'
    }
  };
</script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
MathJax offers more extensive LaTeX support, which might be necessary for very complex mathematical content.

Conclusion

Adding mathematical equations to your Astro markdown files enhances your content’s expressiveness and professionalism. Whether you’re writing technical documentation, educational content, or scientific articles, the ability to include properly formatted equations is invaluable.

Remember that while this tutorial focuses on Astro, the same LaTeX syntax works across many platforms that support KaTeX or MathJax.

By following this guide, you’ve learned:

  1. How to set up KaTeX in your Astro project
  2. How to write inline and block equations
  3. Examples of complex mathematical formulas
  4. Troubleshooting common issues
  5. An alternative approach using MathJax

Now you’re ready to create content with beautiful mathematical equations that render perfectly on your Astro-powered website!

Want to take your math content further? Consider adding interactive elements with JavaScript libraries like Desmos or GeoGebra.