Skip to main content

選擇網頁數學套件:MathJax 和 KaTeX

筆者作為兩者都用過的人,而且都用最新版的(截至 2026/11),勉強算是有資格來寫這篇文章。

如何選擇​

兩者都可以伺服器端渲染,不需客戶端 JS,MathJax 用 Node JS,KaTeX 用 Wasm,伺服器渲染後就是 SVG,沒有不需要 JS,也不會有 JS 提供的額外功能。如果用客戶端 JS 渲染的話,MathJax 的 JS 有很多功能,包含複製 Tex 源碼,無障礙功能如點字、朗讀,複製 Tex 源碼滿爽的,這功能筆者私心加分,這些功能 KaTeX 都沒有。

如果你需要認真寫公式,MathJax 的核心優勢是支援更多 LaTeX 語法,這是非常直觀且重要的問題,能不能渲染一翻兩瞪眼,寫 LaTeX 就是要到處都能跑,語法不支援就很煩。

MathJax 需要的額外 CSS/JS 比 KaTeX 更多,維護負擔更重。

MathJax 的執行速度在現在的版本已經不再是問題,不應該為了速度而放棄他們的核心差異。

選擇就是根據上面自行評估你的情況適合哪個,不再需要考量速度問題,只考慮上面提到的幾個核心差異,就這麼簡單。

至於其他數學套件筆者有找 Claude 調查研究,結論是缺點過多,沒有理由選 MathJax 和 KaTeX 以外的套件。

MathJax 設定​

同場加映 MathJax 完整設定方案,這是 4.1.1 版本的設定,用在 client-side routing 的網站,JS 啟動和清除是讓 Claude 讀 MathJax 源碼寫出來的,都是調用內部 API,僅 4.1.1 適用。如果你的網站不是 client-side routing,叫 AI 把 JS routing 相關邏輯移除就好了。

mathjax-src 是在渲染時就把所有數學包在 span wrapper 裡面,用於定位和設定橫向捲軸。

相關的路徑要改成你自己的,套件包含 @mathjax/mathjax-tex-font, @mathjax/mathjax-newcm-font, @mathjax/mathjax-mhchem-font-extension。

CSS:

/* display=true: block only */
.mathjax-src:has(> mjx-container[display='true']) {
display: block;
width: 100%;
max-width: 100%;
overflow-x: auto;
}
mjx-container[display] {
padding: 1.2em 0.5em !important;
}
mjx-container svg {
display: inline;
}
span.mathjax-src {
color: transparent;
}
span.mathjax-src:has(mjx-container) {
color: inherit;
}
@media (scripting: none) {
span.mathjax-src {
display: none;
}
}

JS:

// called by swup hook
// this is inferred from the source code of mathjax and only for v4.1.1
const resetMath = () => {
const doc = window.MathJax.startup?.document;
if (!doc) return;
doc.clear();
doc.reset({ all: true });
};

let chain = Promise.resolve();

window.__mathTypeset = () => {
chain = chain
.catch(() => {})
.then(() => {
resetMath();
return window.MathJax.typesetPromise?.();
});
return chain;
};

window.__mathClear = resetMath;

window.MathJax = {
loader: {
paths: {
fonts: '/yore/lib/mathjax-fonts',
'mathjax-mhchem-extension': '/yore/lib/mathjax-fonts/mathjax-mhchem-font-extension',
},
load: [
'input/tex',
'output/svg',
'[tex]/physics',
'[tex]/upgreek',
'[tex]/noerrors',
'[tex]/mhchem',
'[tex]/cancel',
'[tex]/color',
'[tex]/boldsymbol',
'[tex]/amscd',
'[tex]/unicode',
],
},
output: {
font: 'mathjax-tex',
fontPath: '/yore/lib/mathjax-tex-font',
},
options: {
skipHtmlTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code'],
},
tex: {
packages: {
'[+]': ['ams', 'mhchem', 'physics', 'upgreek', 'cancel', 'color', 'boldsymbol', 'amscd', 'unicode'],
},
tags: 'ams',
tagSide: 'right',
tagIndent: '0.8em',
displayMath: [
['\\[', '\\]'],
['$$', '$$'],
],
inlineMath: [
['$', '$'],
['\\(', '\\)'],
],
},
startup: {
typeset: false,
ready: () => {
MathJax.startup.defaultReady();
MathJax.startup.promise.then(() => window.__mathTypeset());
},
},
};
import * as params from '@params';
import { once } from '../../core/js/utils.js';
import { registerRouteHook } from '../../core/js/route.js';

// 第一次看到只載入一次 JS
const loadMath = once(async () => {
await import(params.mathJS);
// MathJax can't find document.currentScript when loaded as a module, the component root must be set explicitly
window.MathJax.loader.paths.mathjax = params.texSvgJS.replace(/\/[^/]*$/, '');
await import(params.texSvgJS);
});

// 換頁更新的函式
registerRouteHook(() => {
if (!document.getElementById('math-flag')) return;
loadMath()
.then(() => window.__mathTypeset?.())
.catch(console.error);
return () => window.__mathClear?.();
});

很煩人的是要寫 window.MathJax,以及內部不提供清理函式,所以連 resetMath 都需要讀源碼調用內部 API。CSS 也不遑多讓,雖然結論只有少少幾行,但是第一眼看到 MathJax 渲染出那一大坨 DOM 還真不知從何下手,維護負擔明顯比 KaTeX 重的多。