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.
Table of Contents
Section titled “Table of Contents”- Why Does It Work in VS Code Preview but Not in Astro?
- What Do We Need to Install?
- Install the Required Packages
- Configure
astro.config.mjs - Add KaTeX CSS
- How to Write Math Formulas in Markdown
- Complete Configuration Example
- How to Test It
- Common Problems and Troubleshooting
- How It Works
- 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-mathrehype-katexkatex
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 formulas2. What Do We Need to Install?
Section titled “2. What Do We Need to Install?”The main packages required are:
| Package | Purpose |
|---|---|
remark-math | Allows the Markdown parser to recognise $...$ and $$...$$ math syntax |
rehype-katex | Renders math nodes as KaTeX HTML |
katex | Provides the actual math rendering and styling |
@astrojs/markdown-remark | Astro’s Markdown processor; newer Astro versions can configure Remark / Rehype plugins through unified() |
A simple way to understand their roles:
remark-math = recognise formulasrehype-katex = convert formulaskatex = display formulas3. Install the Required Packages
Section titled “3. Install the Required Packages”First, go to the root folder of your Astro blog project.
For example:
cd C:\Users\harry\MyWorks\Sources\harrylo.com\blogThen run:
npm install remark-math rehype-katex katex @astrojs/markdown-remarkAfter installation, you can verify the packages with:
npm list remark-math rehype-katex katex @astrojs/markdown-remarkIf the packages are installed correctly, you should see their installed versions.
4. Configure astro.config.mjs
Section titled “4. Configure astro.config.mjs”Recommended Approach for Newer Astro 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.mjswith 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.
5. Add KaTeX CSS
Section titled “5. Add KaTeX CSS”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',],6. How to Write Math Formulas in Markdown
Section titled “6. How to Write Math Formulas in Markdown”6.1 Inline Formula
Section titled “6.1 Inline Formula”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$.6.2 Block Formula
Section titled “6.2 Block Formula”For a formula on its own line, use double $$:
$$E = mc^2$$For example:
$$z = \frac{x-\mu}{\sigma}$$6.3 Fractions
Section titled “6.3 Fractions”$$\frac{a}{b}$$6.4 Powers
Section titled “6.4 Powers”$$x^2 + y^2 = z^2$$6.5 Subscripts
Section titled “6.5 Subscripts”$$P_t$$For example:
$$Momentum_{12M}$$6.6 Summation
Section titled “6.6 Summation”$$SMA_n =\frac{1}{n}\sum_{i=0}^{n-1} P_{t-i}$$6.7 Square Root
Section titled “6.7 Square Root”$$\sigma = \sqrt{\frac{1}{N}\sum_{i=1}^{N}(x_i-\mu)^2}$$6.8 MarketLens Momentum Formula Example
Section titled “6.8 MarketLens Momentum Formula Example”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$$6.9 Z-score
Section titled “6.9 Z-score”$$z =\frac{x-\mu}{\sigma}$$6.10 Multi-line Formula
Section titled “6.10 Multi-line Formula”$$\begin{aligned}Return &= \frac{P_t - P_{t-1}}{P_{t-1}} \\Momentum &= \frac{P_t}{P_{t-n}} - 1\end{aligned}$$7. Complete Configuration Example
Section titled “7. Complete Configuration Example”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.
8. How to Test It
Section titled “8. How to Test It”Live preview (this page)
Section titled “Live preview (this page)”If setup is correct, these formulas render below (not inside a code block):
Einstein’s equation is .
Create a simple test page, for example:
src/content/docs/test-math.mdOr 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:
npm run devOpen your local website and view the test page.
9. Common Problems and Troubleshooting
Section titled “9. Common Problems and Troubleshooting”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:
npm install @astrojs/markdown-remarkProblem 4: Build Cannot Find remark-math
Section titled “Problem 4: Build Cannot Find remark-math”Run:
npm install remark-mathProblem 5: Build Cannot Find rehype-katex
Section titled “Problem 5: Build Cannot Find rehype-katex”Run:
npm install rehype-katexProblem 6: KaTeX CSS Cannot Be Found
Section titled “Problem 6: KaTeX CSS Cannot Be Found”Make sure KaTeX is installed:
npm install katexThen verify:
npm list katexProblem 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:
```mermaidgraph 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.10. How It Works
Section titled “10. How It Works”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 │ ▼BrowserThe three components have different roles:
remark-math
Section titled “remark-math”Responsible for:
"This section is a mathematical formula."rehype-katex
Section titled “rehype-katex”Responsible for:
"Convert this formula into HTML that a browser can display."Responsible for:
"Format and display the formula as properly typeset mathematics."11. Recommended Setup
Section titled “11. Recommended Setup”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+KaTeXAfter 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.
Final Checklist
Section titled “Final Checklist”After completing the setup, confirm:
-
remark-mathis installed -
rehype-katexis installed -
katexis installed -
@astrojs/markdown-remarkis installed / can be imported -
astro.config.mjsimportsunified -
remarkPluginsincludesremarkMath -
rehypePluginsincludesrehypeKatex - Starlight
customCssincludeskatex/dist/katex.min.css - Existing bilingual / Mermaid / sidebar settings are preserved
-
npm run devstarts successfully - Inline
$...$formulas render correctly - Block
$$...$$formulas render correctly -
npm run buildcompletes successfully
Official References
Section titled “Official References”- Astro Markdown documentation: https://docs.astro.build/en/guides/markdown-content/
- Starlight configuration: https://starlight.astro.build/reference/configuration/
- remark-math / rehype-katex: https://github.com/remarkjs/remark-math
- KaTeX: https://katex.org/
One-Sentence Summary
Section titled “One-Sentence Summary”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