Astro 展示 數學公式
版本:2026年 9月 25日
適用情況:Markdown 入面嘅數學公式喺 VS Code Preview 可以正常顯示,但喺 Astro / Starlight blog 網頁入面只見到原始$...$、$$...$$,或者完全顯示唔正常。
- 點解 VS Code Preview 到,但 Astro Blog 出唔到?
- 我哋要安裝啲乜?
- 安裝套件
- 設定
astro.config.mjs - 加入 KaTeX CSS
- Markdown 入面點寫公式
- 完整設定例子
- 點樣測試
- 常見問題及 Troubleshooting
- 原理簡介
- 建議做法
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-mathrehype-katexkatex
處理流程大概係:
Markdown ↓remark-math ↓辨認 $...$ / $$...$$ 為數學公式 ↓rehype-katex ↓將公式轉成可以喺 Browser 顯示嘅 HTML ↓KaTeX CSS ↓Browser 正確顯示數學公式2. 我哋要安裝啲乜?
Section titled “2. 我哋要安裝啲乜?”主要需要以下 package:
| Package | 用途 |
|---|---|
remark-math | 令 Markdown parser 認得 $...$ 同 $$...$$ 數學語法 |
rehype-katex | 將數學節點 render 成 KaTeX HTML |
katex | 真正提供公式 rendering 同 styling |
@astrojs/markdown-remark | Astro 官方 Markdown processor;新版 Astro 建議透過 unified() 設定 Remark / Rehype plugins |
簡單理解:
remark-math = 認公式rehype-katex = 轉公式katex = 顯示公式3. 安裝套件
Section titled “3. 安裝套件”先去到 Astro blog project root。
例如:
cd C:\Users\harry\MyWorks\Sources\harrylo.com\blog然後執行:
npm install remark-math rehype-katex katex @astrojs/markdown-remark完成後,可以檢查:
npm list remark-math rehype-katex katex @astrojs/markdown-remark如果 package 正常安裝,就應該會見到相關版本。
4. 設定 astro.config.mjs
Section titled “4. 設定 astro.config.mjs”新版 Astro 建議方式
Section titled “新版 Astro 建議方式”新版 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。
5. 加入 KaTeX CSS
Section titled “5. 加入 KaTeX CSS”就算 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',],6. Markdown 入面點寫公式
Section titled “6. Markdown 入面點寫公式”6.1 Inline Formula
Section titled “6.1 Inline Formula”Inline formula 用單一 $:
Einstein's equation is $E = mc^2$.例如:
The momentum score is calculated using $M = \frac{P_t}{P_{t-n}} - 1$.6.2 Block Formula
Section titled “6.2 Block Formula”獨立一行嘅公式可以用雙 $:
$$E = mc^2$$例如:
$$z = \frac{x-\mu}{\sigma}$$6.3 分數
Section titled “6.3 分數”$$\frac{a}{b}$$6.4 次方
Section titled “6.4 次方”$$x^2 + y^2 = z^2$$6.5 下標
Section titled “6.5 下標”$$P_t$$例如:
$$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”例如 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$$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. 完整設定例子
Section titled “7. 完整設定例子”假設原本係一個簡單 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 設定唔應該被刪除。
8. 點樣測試
Section titled “8. 點樣測試”即時預覽(本頁)
Section titled “即時預覽(本頁)”如果設定正確,下面公式會直接 render(唔係 code block 入面):
Einstein’s equation is .
建議建立一個簡單測試 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$$然後:
npm run dev開啟本地網站,再睇個 test page。
9. 常見問題及 Troubleshooting
Section titled “9. 常見問題及 Troubleshooting”問題 1:網頁仍然顯示 $E = mc^2$
Section titled “問題 1:網頁仍然顯示 $E = mc^2$”即係 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'執行:
npm install @astrojs/markdown-remark問題 4:Build 話搵唔到 remark-math
Section titled “問題 4:Build 話搵唔到 remark-math”執行:
npm install remark-math問題 5:Build 話搵唔到 rehype-katex
Section titled “問題 5:Build 話搵唔到 rehype-katex”執行:
npm install rehype-katex問題 6:KaTeX CSS 搵唔到
Section titled “問題 6:KaTeX CSS 搵唔到”確認:
npm install katex然後:
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 通常處理:
```mermaidgraph 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.10. 原理簡介
Section titled “10. 原理簡介”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所以三個角色唔一樣:
remark-math
Section titled “remark-math”負責:
「呢一段係數學公式」rehype-katex
Section titled “rehype-katex”負責:
「將呢條公式變成 Browser 可以顯示嘅 HTML」負責:
「將公式排版得似真正數學公式」11. 建議做法
Section titled “11. 建議做法”對一個會放 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。
最後檢查 Checklist
Section titled “最後檢查 Checklist”完成後確認:
- 已安裝
remark-math - 已安裝
rehype-katex - 已安裝
katex - 已安裝 / 可 import
@astrojs/markdown-remark -
astro.config.mjsimport 咗unified -
remarkPlugins包含remarkMath -
rehypePlugins包含rehypeKatex - Starlight
customCss包含katex/dist/katex.min.css - 原有 bilingual / Mermaid / sidebar 設定仍然保留
-
npm run dev可以正常啟動 - Inline
$...$可以顯示 - Block
$$...$$可以顯示 -
npm run build可以成功
- 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/
如果 VS Code Preview 見到數學公式,但 Astro Blog 見唔到,核心解決方法就係:
Markdown + remark-math + rehype-katex + KaTeX CSS = Astro Blog 正常顯示 LaTeX 數學公式