Hexo: 如何在Volantis主题上优雅地书写数学公式

如何在 Volantis 主题上优雅地书写数学公式

数学公式渲染引擎选择

MathJax 方案（兼容性优先）

适合需要完整 LaTeX 支持的场景，尤其推荐用于学术类内容。

KaTeX 方案（性能优先）

适合追求加载速度的场景，KaTeX 渲染速度比 MathJax 快约 60%，但对部分复杂公式支持有限。

Volantis 主题内置前端渲染方案

Volantis 6 中在 front-matter 中配置页面插件... 即可。

front-matter

---
plugins:
  - mathjax
  - katex
---

例如：

example.md:

---
title: 渲染公式（MathJax）
date: 2025-10-25
plugins:
  - mathjax
---

添加一段描述性文字

<!-- more -->

$$
\eta(s) = (1-2^{1-s})\zeta(s)
$$

数学公式的语法冲突

这里以 Mathjax 为例：

Mathjax 与 Markdown 的语法冲突

MathJax 与 Markdown 的语法冲突源于两者部分符号的语义重叠，如 _（Markdown 斜体 vs LaTeX 下标）、*（Markdown 粗体 vs LaTeX 星号）和 \（Markdown 转义符 vs LaTeX 命令前缀）。例如，公式 x_i 可能被 Markdown 引擎误解析为 <em>i</em> 标签，导致 MathJax 无法识别。

一种方法是使用 \ 转义这些冲突的部分符号。例如：对于多行公式中的换行 \\ ，需要转义成 \\\\ 。

另一种方法是逆向渲染流程，先让 MathJax 解析公式，再用 Markdown 引擎处理文本。由于理论上 MathJax 生成的 HTML 不含 Markdown 语法，可从根本上避免冲突。

还有一种方案是修改 Markdown 引擎规则，移除语义重叠的部分。

极端的方案是直接使用图片。

Mathjax 与 Nunjucks 的语法冲突

Nunjucks 是 Hexo 内置的模板语法。

Nunjucks 模板引擎与 MathJax 的语法冲突主要源于两者对特殊字符的解析规则重叠。

符号优先级冲突：

MathJax 的 _（下标）和 ^（上标）会被 Nunjucks 误认为模板语法的一部分。例如 x_i 可能被解析为变量 i 的属性，而非数学符号 x_i 。类似地， \frac{1}{2} 中的反斜杠可能被 Nunjucks 转义为普通字符，导致 MathJax 无法识别分式结构。

模板变量标识符冲突：

MathJax 的某些分隔符（如 `$$..$$` ）虽然与 Nunjucks 的 `{{ }}` 不直接重叠，但复杂公式中嵌套的大括号 `{ }` 可能触发模板引擎的语法检查错误，尤其在未正确转义时。一种解决方法是加空格，例如在两个连续的大括号之间加入空格。另一种解决方法是在公式前后添加 Nunjucks 的 raw 标签，使模板引擎跳过对中间内容的解析：

{% raw %}
$$ E=mc^2 $$  <!-- 不受 Nunjucks 影响的公式 -->
{% endraw %}

这种解决方法适用于单页少量公式，无需修改全局配置。缺点是侵入式语法，降低文档可移植性。

第三方插件数学公式渲染器的选择

第三方数学公式渲染器插件需要配套使用对应的 markdown 渲染器才能解决语义重叠冲突的问题。

以下是推荐的组合：

marked

对于 hexo-renderer-marked 配套使用 hexo-xmath 。

或者直接使用懒人包 hexo-xm ，开箱即用。

pandoc

对于 hexo-renderer-pandoc 配套使用 hexo-filter-mathjax 。

使用 pandoc 正确渲染多行 MathJax 公式

markdown-it

对于 hexo-renderer-markdown-it-plus 配套使用 @iktakahiro/markdown-it-katex 。