mdbook-katex 操作手册
mdbook-katex 用于在 mdBook 中渲染 LaTeX 数学公式，适合论文笔记、推导、算法复杂度和技术文档。
原仓库：https://github.com/lzanini/mdbook-katex
行内公式
样例
向量范数写作 ，余弦相似度可以写作 。
对应源码：
向量范数写作 $\|x\|_2$，余弦相似度可以写作 $\frac{x\cdot y}{\|x\|\|y\|}$。
行内公式使用单个 $...$。
块级公式
样例
对应源码：
$$
P(X=k)=\binom{n}{k}p^k(1-p)^{n-k}
$$
块级公式使用 $$...$$。
多行公式
样例
对应源码：
$$
\begin{aligned}
f(x) &= x^2+2x+1 \\
&= (x+1)^2
\end{aligned}
$$
矩阵
样例
对应源码：
$$
A=
\begin{bmatrix}
1 & 2 \\
3 & 4
\end{bmatrix}
$$
分段函数
样例
对应源码：
$$
f(x)=
\begin{cases}
x^2, & x \ge 0 \\
-x, & x < 0
\end{cases}
$$
常用公式写法速查
| 效果 | 源码 |
|---|---|
| 上标 | $x^2$ |
| 下标 | $x_i$ |
| 分数 | $\frac{a}{b}$ |
| 根号 | $\sqrt{x}$ |
| 求和 | $\sum_{i=1}^{n}x_i$ |
| 积分 | $\int_0^1 f(x)\,dx$ |
| 极限 | $\lim_{n\to\infty}a_n$ |
| 向量 | $\mathbf{x}$ |
| 实数空间 | $\mathbb{R}^d$ |
| 属于 | $x\in S$ |
| 近似 | $a\approx b$ |
| 小于等于 | $a\le b$ |
| 大于等于 | $a\ge b$ |
希腊字母
$\alpha, \beta, \gamma, \delta, \epsilon$
$\theta, \lambda, \mu, \sigma, \phi, \omega$
$\Gamma, \Delta, \Theta, \Lambda, \Sigma, \Omega$
对齐长推导
aligned 很适合论文笔记中的连续推导：
$$
\begin{aligned}
T(n)
&= T(n/2)+O(n) \\
&= O(n)+O(n/2)+O(n/4)+\cdots \\
&= O(n)
\end{aligned}
$$
正常显示美元符号
因为 $ 是公式分隔符，如果正文要显示普通美元符号，需要转义：
价格是 \$100。
自定义宏
如果某些表达式频繁出现，可以定义宏文件。
例如 macros.txt：
\grad:{\nabla}
\R:{\mathbb{R}^{#1 \times #2}}
在 book.toml 中指定：
[preprocessor.katex]
macros = "macros.txt"
之后可以在 Markdown 中写：
$$
\grad f(x) \in \R{n}{p}
$$
自定义公式分隔符
默认是：
行内：$ ... $
块级：$$ ... $$
如果希望改成 \(...\) 与 \[...\]：
[preprocessor.katex]
block-delimiter = { left = "\\[", right = "\\]" }
inline-delimiter = { left = "\\(", right = "\\)" }
当前书库配置
[preprocessor.katex]
before = ["links"]
当前采用默认的预渲染模式：公式在构建阶段生成 HTML，页面不依赖客户端 JavaScript 再做公式计算。
KaTeX 必须先于 links 预处理器运行，避免 <、& 和反斜杠等 LaTeX 内容被提前改写。
使用建议
- 句子中的短变量、短表达式使用行内公式；
- 推导、矩阵、分段函数使用块级公式；
- 长公式尽量使用
aligned分行； - 如果公式无法渲染，先检查 KaTeX 是否支持该 LaTeX 命令。