Skip to content

Astro 展示 數學公式

版本:2026年 9月 25日
適用情況:Markdown 入面嘅數學公式喺 VS Code Preview 可以正常顯示,但喺 Astro / Starlight blog 網頁入面只見到原始 $...$、$$...$$,或者完全顯示唔正常。


  1. 點解 VS Code Preview 到,但 Astro Blog 出唔到?
  2. 我哋要安裝啲乜?
  3. 安裝套件
  4. 設定 astro.config.mjs
  5. 加入 KaTeX CSS
  6. Markdown 入面點寫公式
  7. 完整設定例子
  8. 點樣測試
  9. 常見問題及 Troubleshooting
  10. 原理簡介
  11. 建議做法

1. 點解 VS Code Preview 到,但 Astro Blog 出唔到?

Section titled “1. 點解 VS Code Preview 到,但 Astro Blog 出唔到?”

VS Code Markdown Preview 同 Astro 網站其實係兩個唔同嘅 Markdown renderer。

例如 Markdown 有:

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

VS Code 嘅 Markdown Preview 可能本身已經支援數學公式,所以你會見到正常公式。

但 Astro build Markdown 時,預設唔一定會將 $...$ 或 $$...$$ 當成 LaTeX 數學公式。

所以你需要額外加入:

  • remark-math
  • rehype-katex
  • katex

處理流程大概係:

Markdown
↓
remark-math
↓
辨認 $...$ / $$...$$ 為數學公式
↓
rehype-katex
↓
將公式轉成可以喺 Browser 顯示嘅 HTML
↓
KaTeX CSS
↓
Browser 正確顯示數學公式

主要需要以下 package:

Package用途
remark-math令 Markdown parser 認得 $...$ 同 $$...$$ 數學語法
rehype-katex將數學節點 render 成 KaTeX HTML
katex真正提供公式 rendering 同 styling
@astrojs/markdown-remarkAstro 官方 Markdown processor;新版 Astro 建議透過 unified() 設定 Remark / Rehype plugins

簡單理解:

remark-math = 認公式
rehype-katex = 轉公式
katex = 顯示公式

先去到 Astro blog project root。

例如:

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

然後執行:

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

完成後,可以檢查:

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

如果 package 正常安裝,就應該會見到相關版本。


新版 Astro 建議用 markdown.processor 加 unified()。

先喺 astro.config.mjs 加:

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

然後喺 defineConfig() 入面加:

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

例如:

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],
}),
},
});

注意:

唔好直接用上面成份 config 覆蓋你現有嘅 astro.config.mjs。

你原本可能已經有:

  • Starlight sidebar
  • 中文 / 英文 locales
  • social links
  • custom CSS
  • Mermaid
  • site URL
  • 其他 integration

正確做法係將 Math 設定 merge 入去現有 config。


就算 remark-math 同 rehype-katex 已經正常工作,如果冇 KaTeX CSS,公式外觀都可能唔正常。

如果你用 Starlight,可以喺:

starlight({
...
})

入面加入:

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

例如:

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

如果你本身已經有 custom CSS,例如:

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

唔好取代佢。

應該改成:

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

Inline formula 用單一 $:

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

例如:

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

獨立一行嘅公式可以用雙 $:

$$
E = mc^2
$$

例如:

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

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

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

$$
P_t
$$

例如:

$$
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}
$$

例如 12-month price momentum:

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

如果 skip 最近一個月:

$$
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}
$$

假設原本係一個簡單 Starlight config,可以變成:

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],
}),
},
});

再次提醒:

呢個只係示範。

你現有嘅 bilingual / Starlight / Mermaid / sidebar 設定唔應該被刪除。


如果設定正確,下面公式會直接 render(唔係 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

建議建立一個簡單測試 page,例如:

src/content/docs/test-math.md

或者放去你目前 Starlight content folder。

內容:

---
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
$$

然後:

Terminal window
npm run dev

開啟本地網站,再睇個 test page。


即係 remark-math 未有生效。

檢查:

remarkPlugins: [remarkMath]

以及:

import remarkMath from 'remark-math';

問題 2:公式有轉換,但樣式好奇怪

Section titled “問題 2:公式有轉換,但樣式好奇怪”

通常係 KaTeX CSS 未載入。

檢查:

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

問題 3:Build 話搵唔到 @astrojs/markdown-remark

Section titled “問題 3:Build 話搵唔到 @astrojs/markdown-remark”

例如:

Cannot find package '@astrojs/markdown-remark'

執行:

Terminal window
npm install @astrojs/markdown-remark

執行:

Terminal window
npm install remark-math

問題 5:Build 話搵唔到 rehype-katex

Section titled “問題 5:Build 話搵唔到 rehype-katex”

執行:

Terminal window
npm install rehype-katex

確認:

Terminal window
npm install katex

然後:

Terminal window
npm list katex

問題 7:我本身已經有 Remark / Rehype plugin

Section titled “問題 7:我本身已經有 Remark / Rehype plugin”

例如本身有:

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

唔好刪除原本 plugin。

改成:

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

問題 8:我本身有 Mermaid,會唔會撞?

Section titled “問題 8:我本身有 Mermaid,會唔會撞?”

一般情況下唔會。

Mermaid 通常處理:

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

而 KaTeX 處理:

$$
E = mc^2
$$

兩者用途唔同。

不過修改 astro.config.mjs 時,一定要 保留現有 Mermaid plugin / integration。


問題 9:Inline $ 同普通美元符號會唔會混淆?

Section titled “問題 9:Inline $ 同普通美元符號會唔會混淆?”

有可能。

例如文章寫:

The price is $100.

某啲 parser 設定下可能會有歧義。

所以如果文章大量寫貨幣金額,最好測試一下。

需要時可以將美元符號 escape:

The price is \$100.

Astro Markdown processing 可以簡單理解做:

.md file
│
▼
Markdown Parser
│
▼
Remark
│
├── remark-math
│ └── 辨認數學 syntax
│
▼
Markdown AST
│
▼
Rehype
│
├── rehype-katex
│ └── 將 math nodes render 成 KaTeX HTML
│
▼
HTML
│
▼
KaTeX CSS
│
▼
Browser

所以三個角色唔一樣:

負責:

「呢一段係數學公式」

負責:

「將呢條公式變成 Browser 可以顯示嘅 HTML」

負責:

「將公式排版得似真正數學公式」

對一個會放 technical article、AI、Machine Learning、Statistics、Options、MarketLens、數學模型嘅 Astro / Starlight blog,建議正式加入:

remark-math
+
rehype-katex
+
KaTeX

之後文章就可以直接用標準 LaTeX-style Markdown:

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

而唔需要每一頁自己寫 HTML。


完成後確認:

  • 已安裝 remark-math
  • 已安裝 rehype-katex
  • 已安裝 katex
  • 已安裝 / 可 import @astrojs/markdown-remark
  • astro.config.mjs import 咗 unified
  • remarkPlugins 包含 remarkMath
  • rehypePlugins 包含 rehypeKatex
  • Starlight customCss 包含 katex/dist/katex.min.css
  • 原有 bilingual / Mermaid / sidebar 設定仍然保留
  • npm run dev 可以正常啟動
  • Inline $...$ 可以顯示
  • Block $$...$$ 可以顯示
  • npm run build 可以成功


如果 VS Code Preview 見到數學公式,但 Astro Blog 見唔到,核心解決方法就係:

Markdown
+ remark-math
+ rehype-katex
+ KaTeX CSS
= Astro Blog 正常顯示 LaTeX 數學公式