用 Pandoc + MathJax 让 Hexo / Fluid 完整支持 LaTeX 公式

本文给出让 Hexo 用 pandoc 来渲染 Markdown（保留 LaTeX 公式语法），再由 Fluid 主题内置的 MathJax 在前端把这些公式渲染出来的具体方法。➡️

目标：让 Hexo 用 Pandoc 来渲染 Markdown（保留完整的 LaTeX 公式语法），再由 Fluid 主题内置的 MathJax 在前端把这些公式渲染出来。

效果：可以在 Markdown 源代码中直接写

Markdown 代码
效果

.md 文件中写法：

\begin{equation}
\label{eq:einstein_0}
E = mc^2 
\end{equation}

网页渲染出来的效果如下： \[\begin{equation} \label{eq:einstein_0} E = mc^2 \end{equation}\] 引用效果：由式可知，能量与质量成正比。

而不需要再套一层 \[ ... \]，同时支持 align + \tag + \label、矩阵、分段函数、条件概率等复杂公式。

1. 总体思路

渲染流程可以理解为三步：

Hexo 调用 Pandoc 渲染 Markdown
- 用 hexo-renderer-pandoc 替换默认的 hexo-renderer-marked。
- Pandoc 会把文章里的 LaTeX 公式原样保留在 HTML 中。
Fluid 主题加载 MathJax
- 在主题配置里开启 post.math，选择 engine: mathjax。
- MathJax 在浏览器端扫描页面中的 LaTeX 代码并渲染成公式。
在需要公式的文章里打开 math 开关
- 在文章 front-matter 中写 math: true（前提是 specific: true）。
- 然后就可以在 Markdown 中直接使用各种 LaTeX 数学环境。

2. 安装 Pandoc

2.1 检查是否已经安装

在终端（命令行）输入：

1
2
3

pandoc -v
# 或
pandoc --version

如果能看到版本信息（例如 pandoc 3.x），说明已经安装好了，可以跳过下面的安装步骤。

2.2 安装示例

Windows
从 Pandoc 官网下载安装包，安装完成后重新打开终端，再执行一次：
1
pandoc -v
macOS（使用 Homebrew）
1
brew install pandoc

Linux（Debian / Ubuntu 为例）

1 2	`sudo apt-get update sudo apt-get install pandoc`

确保在博客根目录运行 hexo g 时，系统能找到 pandoc 命令，否则 hexo-renderer-pandoc 会报错。

3. 用 hexo-renderer-pandoc 替换默认渲染器

3.1 卸载 Hexo 默认 Markdown 渲染器

在 Hexo 博客根目录 （有 _config.yml 的目录）执行：

1
2
3

# 查看当前安装了哪些 hexo-renderer
npm ls --depth=0 | find "hexo-renderer"    # Windows
# npm ls --depth=0 | grep "hexo-renderer"  # macOS / Linux

常见输出类似：

1
2
3

+-- hexo-renderer-ejs@2.0.0
+-- hexo-renderer-kramed@0.1.4
+-- hexo-renderer-stylus@3.0.1

其中：

hexo-renderer-ejs：渲染主题模板（应该保留）
hexo-renderer-stylus：渲染样式（应该保留）
hexo-renderer-kramed / hexo-renderer-marked：Markdown 渲染器，需要替换为 pandoc

注意：Hexo 里 不要同时安装多个 Markdown 渲染器（比如同时有 hexo-renderer-marked 和 hexo-renderer-pandoc），否则容易冲突。

根据你实际安装的情况卸载（下面给两个常见例子）：

# 示例：卸载 kramed
npm uninstall hexo-renderer-kramed --save

# 如果还有 marked，也卸载掉
npm uninstall hexo-renderer-marked --save

3.2 安装 hexo-renderer-pandoc

继续在博客根目录执行：

1	`npm install hexo-renderer-pandoc --save`

再次确认：

1	`npm ls --depth=0 \| find "hexo-renderer"`

理想状态：

1
2
3

+-- hexo-renderer-ejs@2.0.0
+-- hexo-renderer-pandoc@1.x.x
+-- hexo-renderer-stylus@3.0.1

安装完成后，可以检查 package.json 中的依赖（示例）：

{
  "dependencies": {
    "hexo": "^7.0.0",
    "hexo-renderer-pandoc": "^0.2.1"
  }
}

4. 在 Fluid 主题中开启 LaTeX + MathJax

Fluid 主题本身内置了对 LaTeX 数学公式的支持，只需要正确配置即可。

4.1 在 Hexo `_config.yml` 中配置 pandoc 参数（开启 MathJax）

在博客根目录打开 _config.yml，添加（或合并）如下片段：

pandoc:
  # 如果 pandoc 已经在 PATH 中，可以不写 pandocPath
  # pandocPath: pandoc
  args:
    - --mathjax

关键是 --mathjax：让 pandoc 把 TeX 数学环境原样保留为 MathJax 需要的格式，而不是尝试转成别的东西。

改完后保存即可。

4.2 在 `_config.fluid.yml` 中启用 MathJax

根目录有一个专门的主题配置文件 _config.fluid.yml，打开后找到/添加：

post:
  math:
    enable: true      # 建议设置为 true：只有在 front-matter 写了 math: true 的文章才会加载 MathJax
    specific: true    # true: 只对 math: true 的文章启用，推荐
    engine: mathjax   # 使用 MathJax 作为前端渲染引擎

当 specific: true 时，在 需要公式的文章 front-matter 里 需要显式打开 math，例如：

---
title: 使用 Pandoc + MathJax 写公式
date: 2025-12-09 21:00:00
categories:
  - 博客折腾
tags:
  - Hexo
  - Pandoc
  - MathJax
math: true         # ★ 这一行非常关键
---

如果在主题配置中把 specific 设成了 false，那就不需要在每篇文章中写 math: true，所有文章默认都会加载公式渲染（但性能略差一点）。

4.3 配置 Fluid 主题的 MathJax（让 equation/align/cases 等全部可用）

找到 MathJax 的配置文件路径：

1	`node_modules/hexo-theme-fluid/layout/_partials/plugins/math.ejs`

打开 math.ejs 后，大致会看到类似（伪代码，结构大致这样）：

<% if (theme.post.math.engine === 'mathjax') { %>
  <script>
    window.MathJax = {
      tex: {
        inlineMath: { '[+]': [['$', '$']] },
        displayMath: { '[+]': [['$$', '$$'], ['\\[', '\\]']] },
        // ★ 关键 1 ：打开 AMS 风格自动编号 + \label/\eqref 支持
        tags: 'ams',   // 可选: 'none' | 'ams' | 'all'
        // ★ 关键 2：确保 AMS 扩展加载（包含 align、cases、\tag 等）
        packages: { '[+]': ['ams'] }
      },
      // 其它配置...
    };
  </script>
  <script src="...tex-mml-chtml.js"></script>
<% } else if (theme.post.math.engine === 'katex') { %>
  ...
<% } %>

在 window.MathJax 的 tex 里面加上 tags: 'ams'，让 MathJax 按 AMS 规则自动编号。

AMS 规则指 AMS-LaTeX 的排版规范：比如公式编号、环境（align、theorem 等）、参考文献格式等。

5. 在 Markdown 中书写 LaTeX 公式（重点例子）

下面所有例子都假设：

渲染器已经换成 hexo-renderer-pandoc；
Fluid 主题 post.math 已开启；
当前文章 front-matter 中有 math: true（如果 specific: true）。

.md 文件中写法：

1	`这是一个行内公式 $E = mc^2$，这是另一个行内公式 $\alpha + \beta = \gamma$。`

这是一个行内公式 $E = mc^2$，这是另一个行内公式 $\alpha + \beta = \gamma$。

5.2 行间公式（单行）

两种常用写法都支持：

Markdown 代码
效果

.md 文件中写法：

1
2
3

$$
E = mc^2
$$

\[ E = mc^2 \]

或者直接使用 equation 环境（推荐）：

Markdown 代码
效果

\begin{equation}
\label{eq:einstein_1}
  E = mc^2
\end{equation}

网页渲染效果如下： \[\begin{equation} \label{eq:einstein_1} E = mc^2 \end{equation}\] 引用效果：。

在正文中引用时，可以用 \eqref：

1	`由式 \eqref{eq:einstein} 可知，能量与质量成正比。`

关键点：
使用 Pandoc + MathJax 之后，可以直接写 \begin{equation}...\end{equation}，不需要再额外套一层 \[ ... \]。

5.3 多行对齐 + `\tag` + `\label`

align 环境可以同时对多行公式进行对齐，还可以配合 \tag 和 \label 使用：

Markdown 代码
效果

\begin{align}
  y &= ax + b, \label{eq:line} \\
  f(x) &= ax^2 + bx + c, \label{eq:quad} \\
  E &= mc^2 \tag{Einstein} \label{eq:einstein}
\end{align}

\[\begin{align} y &= ax + b, \label{eq:line} \\ f(x) &= ax^2 + bx + c, \label{eq:quad} \\ E &= mc^2 \tag{Einstein} \label{eq:einstein} \end{align}\] 引用效果：、、。

5.4 矩阵

Markdown 代码
效果

\begin{equation}
  \boldsymbol{A} =
  \begin{bmatrix}
    1 & 2 & 3 \\
    4 & 5 & 6
  \end{bmatrix}.
\end{equation}

\[\begin{equation} \boldsymbol{A} = \begin{bmatrix} 1 & 2 & 3 \\ 4 & 5 & 6 \end{bmatrix}. \end{equation}\]

也可以用 pmatrix 得到带圆括号的矩阵：

Markdown 代码
效果

\begin{equation}
  \boldsymbol{x}_t =
  \begin{pmatrix}
    V_{1,t} \\
    V_{2,t} \\
    \vdots \\
    V_{n,t}
  \end{pmatrix}.
\end{equation}

\[\begin{equation} \boldsymbol{x}_t = \begin{pmatrix} V_{1,t} \\ V_{2,t} \\ \vdots \\ V_{n,t} \end{pmatrix}. \end{equation}\]

5.5 分段函数

Markdown 代码
效果

\begin{equation}
  f(x) =
  \begin{cases}
    \lambda e^{-\lambda x}, & x \ge 0, \\
    0, & x < 0.
  \end{cases}
\end{equation}

\[\begin{equation} f(x) = \begin{cases} \lambda e^{-\lambda x}, & x \ge 0, \\ 0, & x < 0. \end{cases} \end{equation}\]

5.6 条件概率与更复杂的符号

Markdown 代码
效果

1
2
3

\begin{equation}
  \mathbb{P}(A \mid B) = \frac{\mathbb{P}(A \cap B)}{\mathbb{P}(B)}.
\end{equation}

\[\begin{equation} \mathbb{P}(A \mid B) = \frac{\mathbb{P}(A \cap B)}{\mathbb{P}(B)}. \end{equation}\]

还可以写期望、协方差等：

Markdown 代码
效果

\begin{align}
  \mathbb{E}[X]
    &= \int_{-\infty}^{+\infty} x f_X(x)\, \mathrm{d}x, \\
  \operatorname{Cov}(X,Y)
    &= \mathbb{E}\!\big[(X - \mathbb{E}[X])(Y - \mathbb{E}[Y])\big].
\end{align}

\[\begin{align} \mathbb{E}[X] &= \int_{-\infty}^{+\infty} x f_X(x)\, \mathrm{d}x, \\ \operatorname{Cov}(X,Y) &= \mathbb{E}\!\big[(X - \mathbb{E}[X])(Y - \mathbb{E}[Y])\big]. \end{align}\]

这些都是标准 LaTeX 语法，由 Pandoc 原样保留，再交给 MathJax 在浏览器端渲染。

6. 生成并本地预览

每次修改配置或写完文章后，可以在博客根目录执行：

1
2
3

hexo clean
hexo g
hexo s

然后在浏览器中访问：

1	`http://localhost:4000`

打开含有公式的文章，确认：

公式渲染正常；
\tag、\label、\eqref 引用正常；
多行 align、矩阵、分段函数、条件概率等都能正确显示。

到这里，这一套“Hexo 用 Pandoc 渲染 Markdown + Fluid / MathJax 前端公式渲染”的完整流程就配置好了，之后写 Hexo 博客就可以像写 LaTeX 论文一样放心使用各种数学环境了。

编程 > web

#Hexo,Fluid,Pandoc,MathJax

用 Pandoc + MathJax 让 Hexo / Fluid 完整支持 LaTeX 公式

https://nanana-szz.github.io/03-pandoc_MathJax/

作者

John Doe

发布于

2025年12月9日

许可协议

电力系统中的最优潮流（OPF）基础讲解上一篇

Hexo + Fluid 中使用选项卡（Tabs）踩坑记录下一篇

用 Pandoc + MathJax 让 Hexo / Fluid 完整支持 LaTeX 公式

1. 总体思路

2. 安装 Pandoc

2.1 检查是否已经安装

2.2 安装示例

3. 用 hexo-renderer-pandoc 替换默认渲染器

3.1 卸载 Hexo 默认 Markdown 渲染器

3.2 安装 hexo-renderer-pandoc

4. 在 Fluid 主题中开启 LaTeX + MathJax

4.1 在 Hexo _config.yml 中配置 pandoc 参数（开启 MathJax）

4.2 在 _config.fluid.yml 中启用 MathJax

4.3 配置 Fluid 主题的 MathJax（让 equation/align/cases 等全部可用）

5. 在 Markdown 中书写 LaTeX 公式（重点例子）

5.1 行内公式

5.2 行间公式（单行）

5.3 多行对齐 + \tag + \label

5.4 矩阵

5.5 分段函数

5.6 条件概率与更复杂的符号

6. 生成并本地预览

4.1 在 Hexo `_config.yml` 中配置 pandoc 参数（开启 MathJax）

4.2 在 `_config.fluid.yml` 中启用 MathJax

5.3 多行对齐 + `\tag` + `\label`