Jekyll+Kramdown环境下Mathjax渲染LaTeX公式异常问题

核心原因 #

1. Kramdown解析冲突：Kramdown会优先解析Markdown语法，当公式中包含等号（=）、下划线（_）或换行时，可能被误识别为Markdown的标题、强调或换行格式，导致Mathjax接收到的LaTeX代码不完整或被篡改。
2. Mathjax宏包支持缺失：bmatrix属于amsmath宏包的内容，若Mathjax默认未加载该包，无法识别这类环境。
3. 公式分隔符兼容问题：若使用的公式分隔符未被Kramdown标记为“数学内容”，内部符号会被错误解析为Markdown元素。

解决办法 #

1. 配置Kramdown正确识别数学公式 #

在项目根目录的_config.yml中添加或修改以下配置：

kramdown:
  math_engine: mathjax
  parse_block_html: true

math_engine: mathjax会让Kramdown将公式块直接传递给Mathjax，不再解析内部的Markdown语法；parse_block_html确保HTML块（包括Mathjax脚本）被正确处理。

2. 让Mathjax加载必要宏包 #

在_layouts/default.html的Mathjax脚本中，添加amsmath包支持：

<script>
MathJax = {
  tex: {
    packages: {'[+]': ['ams']} // 加载amsmath包，支持bmatrix等环境
  }
};
</script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

3. 使用标准公式分隔符 #

• 块级公式（独立成行）：使用$$ ... $$或\[ ... \]，如需换行用LaTeX的\\命令，不要用Markdown的直接回车换行。
  示例：

  $$
  \begin{bmatrix}
  a_{11} & a_{12} & \dots & a_{1n} \\
  a_{21} & a_{22} & \dots & a_{2n} \\
  \vdots & \vdots & \ddots & \vdots \\
  a_{m1} & a_{m2} & \dots & a_{mn}
  \end{bmatrix} = \mathbf{A}
  $$
  

• 行内公式：使用$ ... $或\( ... \)，确保符号被包裹在分隔符内，避免被Kramdown误解析。

4. 规避语法冲突 #

公式内的Markdown敏感符号（如下划线、星号）只要放在公式分隔符内部，Kramdown就会将其视为LaTeX内容而非Markdown语法，无需额外转义。

内容的提问来源于stack exchange，提问作者Yorafa