Markdown 里的数学公式——到处能渲染的 LaTeX（以及渲染不了的地方）

1. 为什么 Markdown 里的数学和表格不一样

本簇里的其他一切——表格、代码块、图表——都活在 Markdown 规范或其扩展之内。数学不在。Markdown 里没有「数学语法」；存在的是一个诞生于 Pandoc 和 Jekyll 生态的约定：把 LaTeX 公式记号写进 $...$ 定界符，事后由数学库渲染。

这个区别解释了所有怪癖。$ 在文本里是合法字符（价格！），所以每个渲染器都得靠启发式判断 $...$ 是数学还是钱。不同平台选了不同的启发式、不同的渲染器、不同水平的 LaTeX 支持。结果就是整个格式里最破碎的角落——先知道这一点，能省一小时困惑。

美元符号约定能胜过其他方案，理由很朴素：它在纯文本里站得住。LaTeX 自家的定界符 \( ... \) 和 \[ ... \] 在编辑器里读着别扭，放进 HTML 语境还会跟反斜杠括号撞车；从 MediaWiki Wiki 借来的 <math> 标签则把标记掺进正文，复制粘贴就散架。美元符号视觉上吵，但可读——满屏 $x_i$ 的句子里，你照样能读出公式周围的话。Pandoc、Jekyll 直到最后入场的 GitHub 都收敛到同一个约定，靠的就是这份可读性；而它们为此付出的代价，就是下面这些怪癖。

2. 能用的语法（在能用的地方）

行内公式用单个美元符号包裹；展示公式用双美元符号独立成行：

欧拉恒等式 $e^{i\pi} + 1 = 0$ 内嵌在句子里。

$$
\int_{0}^{\infty} e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

里面的记号是 LaTeX——下标（x_i）、分式（\frac{a}{b}）、希腊字母（\alpha）、求和与积分（\sum、\int）。如果你刚接触 LaTeX，值得花一分钟了解 Markdown 与其他格式的关系：LaTeX 是比 Markdown 年长几十年的完整排版系统，Markdown 数学只借用了它的公式记号，没有借用它的文档类和命令。

两条在所有渲染器下都成立的实用规则。展示公式独立成行——段落内的行内 $..$ 是平台误判的高发区。绝不要依赖表格或标题里的公式——那里支持者寥寥。

实践中说的「LaTeX 记号」，其实是一个够用的子集，不是整套系统。上下标、分式、希腊字母、求和、积分、极限，加上 matrix 或 aligned 环境里的矩阵——这个核心覆盖了技术笔记的绝大多数需求，所有像样的渲染器都支持。自定义宏才是引擎之间分道扬镳的地方：KaTeX 和 MathJax 能展开 \newcommand 和 \def 定义，Obsidian 允许在设置里登记宏，让 $\R$ 悄悄变成 \mathbb{R}，而 GitHub 完全不接受自定义宏。一份文档若依赖手搓宏，就等于揣着一个可移植性风险——对待它要像对待任何平台专属扩展一样认真。

3. 哪里能渲染——2026 年的拼图

GitHub 通过 MathJax 支持了原生数学渲染，自 2022 年上线延续至 2026 年——文件、issue、评论都渲染 $...$ 和 $$...$$。Obsidian 在两种编辑器里都原生渲染。Jekyll 和 Hugo 站点在主题引入 KaTeX 或 MathJax 后渲染——通常是一行 include。静态文档生成器经配置支持。

失败的案例同样一致：纯文本编辑器、严格 CommonMark 渲染器、以及刻意清洗内嵌标记的平台，会把美元符号原样显示。工作流建议与表格和图表相同：先在你发布的环境里渲染一次，再写依赖它的文档。如果文档必须活在许多未知渲染器里，把公式写成展示块，并考虑放一个兜底渲染——同一个 LaTeX 的代码块——给数学画不出来的环境。

拼图内部的差异是成体系的，不是随机分布。引擎要么把数学做成有正式文档的扩展，要么把数学丢给主题——而主题可能永远不会加。把六个环境放在四个问题下对比——行内支持、块级支持、宏支持、各自的标志性翻车方式——就压成了下面这张矩阵。

4. 渲染器支持矩阵

这几行不是排行榜，而是三种哲学的分野。GitHub 和 Typora 押注美元符号约定，用转义规则消化代价；Hugo 正是为了钱的歧义而拒绝裸 $，在文档里推荐 \( \) 作为安全的行内形式，客户端和服务端两套渲染路线都写在 Hugo 的数学文档里。Jekyll 和 Hugo 同属「自带渲染器」一行——生成器只负责把公式原样传下去，真正画出来要靠主题或构建管线装上数学库。Notion 是六个里断裂最深的一个：它支持「公式」这个概念，却不支持纯文本约定，这意味着 .md 文件一进入那个生态，就不再是文档的充分载体。

5. 值得提前了解的翻车坑

这个格式里的每一个坑，都能从两个事实推演出来：渲染器要对 $ 跑启发式，而 Markdown 解析器跑在数学引擎前面。提前认识这四类故障，意味着看到症状就能定位；它们没有一个需要你弃用这个格式。需要的只是分清是哪一层出了问题——定界符启发式、强调解析器，还是 LaTeX 子集。

价格文本撞上美元符号

经典症状是一句「每月 $5、每年 $50」把中间的「每月」渲染成斜体数学糊——因为两个美元符号配了对，中间的文字被当成了公式。原因是配对定界启发式本身：同一行里任意两个 $ 都是候选公式。绕法按可移植性从高到低排：把货币符号转义成 \$5；改写成「5 USD」；或者按 GitHub 数学文档对同行冲突的建议，把符号包进 <span> 标签。各家启发式的激进度还不一样，同一句话在 Obsidian 里没事、到 GitHub 上翻车，就是这么来的。

公式里的下划线和星号被当成强调

症状是公式本身完全合法，但下标变成了斜体字母，星号吞进粗体里消失了。原因是管线顺序：在若干环境里——老式 kramdown 配置、一些 Wiki、一些静态主题——Markdown 的强调处理跑在数学扩展之前，公式里的 _..._ 或 *...* 在它眼里就是标记。首要绕法是给每个下标加花括号（写 x_{i} 而不是 x_i），这本来就是良好的 LaTeX 卫生习惯，多字符下标也一并保住。如果引擎还是误判，把那条公式换成 \( ... \) 定界符——强调处理对它视而不见。

代码块里的公式不渲染——这是设计使然

症状是公式以灰色底上的裸 \int ... 源码示人，原因则是整个领域里最可靠的一条规则：反引号承诺「字面文本」，所有数学引擎都信守这个承诺。代码块存在的意义之一，就是在讲语法的时候展示 LaTeX 源码，所以这个行为不会改。修复很简单：把公式挪出代码格式。同一个承诺也是这个格式最好的兜底——把每条展示公式复制一份成纯 LaTeX 代码块，能渲染的读者看到画好的版本，其余读者看到可读的源码，这就是每个严肃迁移指南都收录这个模式的原因。

多行环境是引擎分歧最大的地方

症状是同一个 align 块在一个引擎里被压成一行、在另一个引擎里正常出图，或者环境整体以裸文本示人。原因是多行数学需要解析器和渲染器同时配合：有的引擎要求环境包在 $$ 里，GitHub 官方指引把多行表达式引向它的 math 代码围栏，而块内一旦出现空行，段落先被切开，数学引擎根本看不到完整的环境。绕法是机械的——aligned 或 align 放进展示块且块内不留空行，优先用平台推荐的围栏，并且用真实环境实测，别想当然认为 $$ 块万无一失。

第五个坑藏在表格里，值得一提：公式里的 |——比如 \{x | x > 0\} 这样的集合构建记法——会终结表格单元格，因为表格解析器跑在前面。转义竖线，或者干脆把这种记法挪出表格。这些故障没有一个会损坏文件，这正是纯文本数学沉默的优势：渲染出错时，源码完好无损、随时可修。

6. KaTeX 还是 MathJax——这个选择重要吗？

如果你自建站点，重要，取舍很简单。KaTeX 同步渲染、速度快——公式多的时候没有排版跳动——这对公式密集的页面很重要。MathJax 渲染慢，但覆盖更广的 LaTeX 宏包和边缘语法——这对话题深入专业记号的文档很重要。平台用户用的是平台内嵌的那个——GitHub 用 MathJax；很多静态主题默认 KaTeX——对常见公式来说实际差异可以忽略。

站点一旦长大，两个二阶差异开始显形。KaTeX 刻意只渲染一个有文档可查的 LaTeX 子集，不支持的就直接拒绝——公式静默失败时，通常该查的是 KaTeX 的支持函数列表，而不是去调试页面。MathJax 追求覆盖面，还带着无障碍机制——包括读屏输出——这也是 GitHub 选它的原因之一。速度差距在公式密集的页面上会累积：五十条公式在 KaTeX 下明显更利索。不想让任何数学库跑在读者浏览器里的自建者，可以在构建期把数学渲染成纯 HTML 交付——Hugo 的服务端管线和若干 Jekyll 插件走的都是这条路。

7. 从 LaTeX 论文迁移到 Markdown

Pandoc 是这场迁移的主力，而它的数学处理恰恰是最不用担心的部分。pandoc paper.tex -o paper.md 会把章节转成标题、脚注转成脚注，公式默认按 $...$ 和 $$...$$ 原样保留——TeX 数学原封不动，Pandoc 手册对其 Markdown 方言有明确文档。导言区则安静地死去：文档类、\usepackage、版式命令在 Markdown 里没有对应物，直接被丢弃。图片要加 --extract-media 才会带出来，图多的论文少了这面旗子就会静默丢失。

公式编号是第一道真实取舍。LaTeX 的 \begin{equation} 加 \label 加 \eqref 机器——带编号、引用稳定的公式——在 Markdown 里没有原生对应物，因为 Markdown 的展示公式按约定不编号。选项有两个：用 pandoc-crossref 这类过滤器，为 HTML 和 LaTeX 输出找回 {#eq:...} 编号和 @eq: 引用；或者接受无编号公式，学着博客腔写「上式」。笔记和讲解不编号活得很好；要送审、要被引用、要付印的东西通常不行。

参考文献的存活率比编号高。Pandoc 的引用处理器能把 \cite{key} 转成 Markdown 式引用，再配一个 .bib 文件和选定的 CSL 样式渲染出来——BibTeX 那套机器大体上能整体搬迁。但每场迁移迟早撞上那个诚实的问题：如果源头是一篇推导密集、交叉引用密布、带浮动图表和文献表的多页论文，转出来的 Markdown 只是一篇更差的 LaTeX 论文，而不是一篇更好的 Markdown 文档。迁笔记、迁讲解、迁概念验证；学位论文让它留在原地。

8. 它到底服务谁：两个真实场景

用量最重的一群人，是在 Obsidian 或 Typora 里记课堂笔记、推导过程和论文精读笔记的研究者与研究生。这里的公式密度是 Markdown 数学所能见的天花板——一段一公式在推导里很常见——而回报正是纯文本买来的东西：跨多年笔记的全文检索、从证明到所引论文的 Wiki 式链接、以及比任何单一应用都活得久的文件。边界同样清楚：要投期刊的稿件留在 LaTeX，那里面的投稿管线、模板文档类和编号参考文献没有商量余地。笔记负责思考，论文负责发表，两种格式分工干净利落。

更轻但规模大得多的一群人，是在 README 和设计文档里写模型规格、算法讲解、指标定义的工程团队。公式密度低——一份文档里几条展示公式——但文档跟代码住在一起，GitHub 让公式随 diff 一起渲染出来。这种就地安放就是全部价值：紧挨着实现代码的损失函数定义，胜过一份没人打开第二次的链接 PDF。文档若住在 Notion，决定就会反转——每条公式都变成一次斜杠命令插入，纯文本往返还会把它们弄丢——迁移之前值得拿一份真实文档先试水。

9. AI 时代改变了什么

手写 LaTeX 一直是真正的门槛：记号可以学会但毫无乐趣，而且漏一个花括号就渲染失败。这道门槛在 AI 助手出现后基本塌了。向 agent 描述「高斯积分等于二分之根号派」，得到的是正确的 LaTeX；在文档站或技术笔记上工作的 agent，会顺手把带定界符的公式直接写进文件。

验证循环也很短——贴进渲染器，看它画不画。也就是说：Markdown 数学的能力下限从「会 LaTeX」移到了「会描述公式」，而格式的碎片化渲染反而成了问题更难的那一半。

实操里顺手的模式是三步：描述、加定界、验证。用文字把公式说清楚，让 agent 去挑记号；把渲染器的原始报错贴回去，让它自己修花括号；要它输出带 aligned 环境的展示块，而不是横跨整段的行内公式。验证习惯比生成能力更重要，因为 agent 对自己 LaTeX 的自信不构成证据——每生成一次就渲染一次。要盯紧目标引擎不支持的东西：GitHub 上的自定义宏，或者只有 MathJax 的宽子集才认识的记法。

更深一层的变化，是公式变成了流水线数据。在建立在 Markdown 之上的 AI 流水线里，公式是一段文本，agent 能生成它、检查它、翻译它、重新渲染它，不需要人重新敲一遍——这与 Markdown 之所以成为机器写文档的交换格式，是同一份性质。新下限要求的不是一门记号课，而是一个检查的习惯。

10. 结语

Markdown 里的数学是一条在自己边界内运转良好的约定：以文字为主的文档、少量公式、一个已知的渲染环境。边界之内，你得到的是纯文本形态的公式——可版本化、可移植、AI 可写。边界之外，数学密集的文档仍然属于 LaTeX 或 Typst——在那里，页面版式和公式编号才是一等公民。

分清自己在写哪种文档，美元符号就不再神秘。实操清单很短：一个已知的渲染环境、要紧的公式一律展示块、货币符号转义、再加上给数学画不出来的地方备一份纯 LaTeX 兜底。这四条做对，这个格式就不再跟你作对。