MDX 使用 KaTeX 渲染 LaTeX 数学公式

LaTeX (GitHub) 是一个完整的文档排版系统，包括页面布局、章节结构、引用、目录等一整套命令体系，其中数学公式是其中的一个子集。

KaTeX (GitHub) 是一个用于在网页上渲染 LaTeX 数学公式的 JavaScript 库。

Next.js + MDX + 静态导出，实现数学公式渲染，使用：remark-math + rehype-katex + katex。

这是一套标准、轻量的方案，KaTeX 可以在构建阶段直接生成公式 HTML，不依赖浏览器端 JS，适合 output: 'export' 静态导出站点。

Markdown/MDX 数学公式渲染流水线：

Markdown/MDX 文本 (含 $...$ 或 $$...$$)
        │
        ▼
   remark-math      ← 在 remark（Markdown AST）阶段，识别数学公式语法
        │              把 $...$ / $$...$$ 标记为特殊的 AST 节点（math/inlineMath）
        ▼
  (remark → rehype 转换，AST 从 mdast 转为 hast)
        │
        ▼
   rehype-katex     ← 在 rehype（HTML AST）阶段，找到这些数学节点
        │              调用 katex 库把公式字符串编译成 HTML/CSS 结构
        ▼
      katex          ← 实际执行渲染计算的核心库
        │              （生成对应的 HTML + KaTeX 自带的 CSS 样式）
        ▼
   最终渲染出的数学公式（网页上可见）

• remark-math：

  • remark 是处理 Markdown 的插件生态，属于 unified 的一部分；
  • 该插件负责识别，扫描 md、mdx 文件，找到 $...$ 和 $$...$$ 标记的数学公式，把它们标记成特殊节点，插入到 Markdown 的抽象语法树（AST）里。
  • 不做什么渲染处理，仅仅负责识别和标记；

• rehype-katex：

  • rehype 是处理 HTML 的插件生态，属于 unified 的一部分；
  • 该插件负责转换，在 HTML AST 阶段，找到上一步的标记，调用 katex 库把公式字符串编译成 HTML/CSS 结构；
  • 是"胶水层"，负责把 katex 这个库接入到 unified/remark/rehype 的处理流水线里；

• katex：

  • 实际执行渲染计算的核心库，接收 LaTeX 语法的字符串（如 \frac{1}{2}），生成对应的 HTML + KaTeX 自带的 CSS 样式；
  • 是"渲染层"，负责把公式字符串编译成 HTML/CSS 结构；
  • 本身跟 Markdown、MDX 没有任何关系，是独立的库，可以脱离这套流水线单独使用；

1. 安装依赖

pnpm add remark-math rehype-katex katex

• remark-math：让 Markdown / MDX 认识 $...$ 和 $$...$$
• rehype-katex：把数学表达式转换成 KaTeX HTML
• katex：提供公式渲染所需的 CSS / 字体等

2. 在 MDX 配置中加入插件

next.config.mjs 大致如下：

const withMDX = createMDX({
    options: mdxOptions,
})
 
const mdxOptions = {
    remarkPlugins: [
        ['remark-gfm', {}],
        ['remark-math', {}],
    ],
    rehypePlugins: ['rehype-slug', ['rehype-pretty-code', rehypePrettyCodeOptions], 'rehype-katex'],
};

3. 引入 KaText CSS

在：

app/layout.tsx

里加入：

import 'katex/dist/katex.min.css'

rehype-katex 负责生成 HTML，但公式的排版样式仍然需要 KaTeX CSS。

4. 基本语法

要掌握 LaTeX 数学语法。

行内公式

MDX：

模型的参数量可以表示为 $N = 27 \times 10^9$。

显示：

模型的参数量可以表示为 $N = 27 \times 10^9$。

独立公式

MDX：

$$
E = mc^2
$$

会独占一行显示。

分数

例如：

$$
\frac{1}{2}
$$

就是：

复杂一点：

$$
\frac{a+b}{c+d}
$$

得到：

关键语法：

\frac{分子}{分母}

其他

Softmax：

$$
P(x_i) =
\frac{e^{z_i}}
{\sum_{j=1}^{n} e^{z_j}}
$$

平均值：

$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i
$$

得到：