Skip to content

Astro displays Math Formula

Version: 25 September 2026 Use this guide when mathematical formulas display correctly in VS Code Markdown Preview, but your Astro / Starlight blog shows the raw $...$, $$...$$, or does not render the formulas correctly.


  1. Why Does It Work in VS Code Preview but Not in Astro?
  2. What Do We Need to Install?
  3. Install the Required Packages
  4. Configure astro.config.mjs
  5. Add KaTeX CSS
  6. How to Write Math Formulas in Markdown
  7. Complete Configuration Example
  8. How to Test It
  9. Common Problems and Troubleshooting
  10. How It Works
  11. Recommended Setup

1. Why Does It Work in VS Code Preview but Not in Astro?

Section titled “1. Why Does It Work in VS Code Preview but Not in Astro?”

VS Code Markdown Preview and your Astro website use different Markdown renderers.

For example, your Markdown may contain:

Inline formula: $E = mc^2$
$$
z = \frac{x-\mu}{\sigma}
$$

VS Code Markdown Preview may already support mathematical formulas, so the formulas appear correctly there.

However, when Astro builds Markdown files, it does not necessarily interpret $...$ or $$...$$ as LaTeX math expressions by default.

Therefore, you need to add:

  • remark-math
  • rehype-katex
  • katex

The processing flow is roughly:

Markdown
↓
remark-math
↓
Recognises $...$ / $$...$$ as mathematical formulas
↓
rehype-katex
↓
Converts formulas into HTML that the browser can display
↓
KaTeX CSS
↓
Browser displays properly formatted mathematical formulas

The main packages required are:

PackagePurpose
remark-mathAllows the Markdown parser to recognise $...$ and $$...$$ math syntax
rehype-katexRenders math nodes as KaTeX HTML
katexProvides the actual math rendering and styling
@astrojs/markdown-remarkAstro’s Markdown processor; newer Astro versions can configure Remark / Rehype plugins through unified()

A simple way to understand their roles:

remark-math = recognise formulas
rehype-katex = convert formulas
katex = display formulas

First, go to the root folder of your Astro blog project.

For example:

Terminal window
cd C:\Users\harry\MyWorks\Sources\harrylo.com\blog

Then run:

Terminal window
npm install remark-math rehype-katex katex @astrojs/markdown-remark

After installation, you can verify the packages with:

Terminal window
npm list remark-math rehype-katex katex @astrojs/markdown-remark

If the packages are installed correctly, you should see their installed versions.


Section titled “Recommended Approach for Newer Astro Versions”

For newer Astro versions, you can configure the Markdown processor using markdown.processor together with unified().

First, add these imports to astro.config.mjs:

import { unified } from '@astrojs/markdown-remark';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

Then add this inside defineConfig():

markdown: {
processor: unified({
remarkPlugins: [remarkMath],
rehypePlugins: [rehypeKatex],
}),
},

For example:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import { unified } from '@astrojs/markdown-remark';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
export default defineConfig({
integrations: [
starlight({
title: 'My Blog',
}),
],
markdown: {
processor: unified({
remarkPlugins: [remarkMath],
rehypePlugins: [rehypeKatex],
}),
},
});

Important:

Do not replace your entire existing astro.config.mjs with the example above.

Your current configuration may already contain:

  • Starlight sidebar settings
  • Chinese / English locales
  • Social links
  • Custom CSS
  • Mermaid
  • Site URL
  • Other integrations

The correct approach is to merge the math configuration into your existing config.


Even if remark-math and rehype-katex are working correctly, the formulas may still look incorrect if the KaTeX stylesheet is not loaded.

If you are using Starlight, add the KaTeX stylesheet inside:

starlight({
...
})

Add:

customCss: [
'katex/dist/katex.min.css',
],

For example:

starlight({
title: 'My Blog',
customCss: [
'katex/dist/katex.min.css',
],
}),

If you already have your own custom CSS, for example:

customCss: ['./src/styles/custom.css'],

do not replace it.

Instead, change it to:

customCss: [
'./src/styles/custom.css',
'katex/dist/katex.min.css',
],

Use a single $ around an inline formula:

Einstein's equation is $E = mc^2$.

For example:

The momentum score is calculated using $M = \frac{P_t}{P_{t-n}} - 1$.

For a formula on its own line, use double $$:

$$
E = mc^2
$$

For example:

$$
z = \frac{x-\mu}{\sigma}
$$

$$
\frac{a}{b}
$$

$$
x^2 + y^2 = z^2
$$

$$
P_t
$$

For example:

$$
Momentum_{12M}
$$

$$
SMA_n =
\frac{1}{n}
\sum_{i=0}^{n-1} P_{t-i}
$$

$$
\sigma = \sqrt{\frac{1}{N}\sum_{i=1}^{N}(x_i-\mu)^2}
$$

For example, a 12-month price momentum formula:

$$
Momentum_{12M}
=
\frac{P_t}{P_{t-252}} - 1
$$

If you want to skip the most recent month:

$$
Momentum_{12-1}
=
\frac{P_{t-21}}{P_{t-252}} - 1
$$

$$
z =
\frac{x-\mu}{\sigma}
$$

$$
\begin{aligned}
Return &= \frac{P_t - P_{t-1}}{P_{t-1}} \\
Momentum &= \frac{P_t}{P_{t-n}} - 1
\end{aligned}
$$

Assuming you originally have a simple Starlight configuration, it could look like this:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import { unified } from '@astrojs/markdown-remark';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
export default defineConfig({
integrations: [
starlight({
title: 'Harry Lo',
customCss: [
'katex/dist/katex.min.css',
],
}),
],
markdown: {
processor: unified({
remarkPlugins: [remarkMath],
rehypePlugins: [rehypeKatex],
}),
},
});

Again:

This is only an example.

Your existing bilingual / Starlight / Mermaid / sidebar settings should not be removed.


If setup is correct, these formulas render below (not inside a code block):

Einstein’s equation is E=mc2E = mc^2.

z=x−μσz = \frac{x-\mu}{\sigma} Momentum12M=PtPt−252−1Momentum_{12M} = \frac{P_t}{P_{t-252}} - 1

Create a simple test page, for example:

src/content/docs/test-math.md

Or place it in your current Starlight content directory.

Use the following content:

---
title: Math Formula Test
---
# Math Formula Test
## Inline
Einstein's equation is $E = mc^2$.
## Fraction
$$
z = \frac{x-\mu}{\sigma}
$$
## Summation
$$
SMA_n =
\frac{1}{n}
\sum_{i=0}^{n-1} P_{t-i}
$$
## Momentum
$$
Momentum_{12M}
=
\frac{P_t}{P_{t-252}} - 1
$$

Then run:

Terminal window
npm run dev

Open your local website and view the test page.


Problem 1: The Website Still Displays $E = mc^2$

Section titled “Problem 1: The Website Still Displays $E = mc^2$”

This usually means remark-math is not being applied.

Check that you have:

remarkPlugins: [remarkMath]

and:

import remarkMath from 'remark-math';

Problem 2: The Formula Is Converted but the Styling Looks Wrong

Section titled “Problem 2: The Formula Is Converted but the Styling Looks Wrong”

This usually means the KaTeX stylesheet has not been loaded.

Check:

customCss: [
'katex/dist/katex.min.css',
],

Problem 3: Build Cannot Find @astrojs/markdown-remark

Section titled “Problem 3: Build Cannot Find @astrojs/markdown-remark”

For example:

Cannot find package '@astrojs/markdown-remark'

Run:

Terminal window
npm install @astrojs/markdown-remark

Run:

Terminal window
npm install remark-math

Run:

Terminal window
npm install rehype-katex

Make sure KaTeX is installed:

Terminal window
npm install katex

Then verify:

Terminal window
npm list katex

Problem 7: I Already Have Remark / Rehype Plugins

Section titled “Problem 7: I Already Have Remark / Rehype Plugins”

For example, your existing configuration may look like this:

markdown: {
processor: unified({
remarkPlugins: [remarkExistingPlugin],
rehypePlugins: [rehypeExistingPlugin],
}),
},

Do not remove the existing plugins.

Instead, change it to:

markdown: {
processor: unified({
remarkPlugins: [
remarkExistingPlugin,
remarkMath,
],
rehypePlugins: [
rehypeExistingPlugin,
rehypeKatex,
],
}),
},

Problem 8: I Already Use Mermaid. Will It Conflict with KaTeX?

Section titled “Problem 8: I Already Use Mermaid. Will It Conflict with KaTeX?”

Normally, no.

Mermaid usually processes blocks such as:

```mermaid
graph TD
A --> B
```

KaTeX processes math such as:

$$
E = mc^2
$$

They serve different purposes.

However, when modifying astro.config.mjs, make sure you keep your existing Mermaid plugin / integration.


Problem 9: Can Inline $ Conflict with Normal Dollar Signs?

Section titled “Problem 9: Can Inline $ Conflict with Normal Dollar Signs?”

It can in some situations.

For example:

The price is $100.

Depending on the parser configuration, this may become ambiguous.

If your article contains many currency values, test them carefully.

When necessary, escape the dollar sign:

The price is \$100.

Astro Markdown processing can be understood like this:

.md file
│
▼
Markdown Parser
│
▼
Remark
│
├── remark-math
│ └── Recognises mathematical syntax
│
▼
Markdown AST
│
▼
Rehype
│
├── rehype-katex
│ └── Renders math nodes as KaTeX HTML
│
▼
HTML
│
▼
KaTeX CSS
│
▼
Browser

The three components have different roles:

Responsible for:

"This section is a mathematical formula."

Responsible for:

"Convert this formula into HTML that a browser can display."

Responsible for:

"Format and display the formula as properly typeset mathematics."

For an Astro / Starlight blog containing technical articles, AI, Machine Learning, Statistics, Options, MarketLens, or mathematical models, it is useful to include:

remark-math
+
rehype-katex
+
KaTeX

After that, your articles can use standard LaTeX-style Markdown directly:

$$
\text{Sharpe Ratio}
=
\frac{R_p - R_f}{\sigma_p}
$$

You do not need to manually write HTML for every formula.


After completing the setup, confirm:

  • remark-math is installed
  • rehype-katex is installed
  • katex is installed
  • @astrojs/markdown-remark is installed / can be imported
  • astro.config.mjs imports unified
  • remarkPlugins includes remarkMath
  • rehypePlugins includes rehypeKatex
  • Starlight customCss includes katex/dist/katex.min.css
  • Existing bilingual / Mermaid / sidebar settings are preserved
  • npm run dev starts successfully
  • Inline $...$ formulas render correctly
  • Block $$...$$ formulas render correctly
  • npm run build completes successfully


If mathematical formulas work in VS Code Preview but not in your Astro blog, the core solution is:

Markdown
+ remark-math
+ rehype-katex
+ KaTeX CSS
= LaTeX formulas rendered correctly in your Astro blog