Jekyll+MathJax环境下GitHub Pages行内LaTeX公式无法渲染排查

在Jekyll搭建的GitHub Pages中，使用$...$格式的行内LaTeX公式时出现渲染异常：公式未被MathJax识别，反而被解析为普通Markdown格式（比如斜体），尝试添加空格拆分公式也无法解决。

异常示例 #

示例1 #

Again employing the linear combination theorem and applying the null hypothesis from \eqref{eq:ttest2-h0}, the distribution of $Z = ( ( \bar{y}_1 - \bar{y}_2 ) - \mu_{\Delta} ) / ( \sigma \sqrt{1/n_1+1/n_2} )$ becomes [standard normal](/D/snorm)

公式未渲染，部分内容被解析为斜体。

示例2 #

where $\bar{y} _i$ is the average of all values $y_{ij}$ from category $i$ and $\bar{y}$ is the grand mean of all values $y_{ij}$ from all categories $i = 1, \ldots, k$.

示例3 #

Here, $\bar{y} _{i j \bullet}$ is the mean for the $(i,j)$-th cell (out of $a \times b$ cells), computed from $n_{ij}$ values $y_{ijk}$, $\bar{y} _{i \bullet \bullet}$ and $\bar{y} _{\bullet j \bullet}$ are the level means for the two factors and and $\bar{y} _{\bullet \bullet \bullet}$ is the mean across all values $y_{ijk}$.

例外情况 #

• 部分包含\bar{...}的公式能正常渲染
• 不含\bar{...}的公式也会出现渲染异常，例如：

示例4 #

where $\bar{y} _{\bullet \bullet \bullet}$, $\bar{y} _{i \bullet \bullet}$, $\bar{y} _{\bullet j \bullet}$ and $\bar{y} _{i j \bullet}$ are the following [sample means](/D/mean-samp):

示例5 #

Note that, because $0 \leq \mathrm{H}_\mathrm{bern}(p) \leq 1$, we have $0 \leq n \cdot \mathrm{H}_\mathrm{bern}(p) \leq n$, and because the [entropy is non-negative](/P/ent-nonneg), it must hold that $n \geq \mathrm{E}_\mathrm{lbc}(n,p) \geq 0$.

问题与排查思路 #

案例差异分析 #

异常案例的共性是公式中包含_（下标）或复杂命令（如\bar、\bullet），这些字符会被Jekyll默认的Markdown解析器（Kramdown）优先处理，破坏$的配对关系，导致MathJax无法识别公式边界。而正常渲染的公式要么_的位置未触发Markdown斜体解析，要么解析器未提前截断公式范围。

具体排查步骤 #

1. 调整Kramdown解析规则
   Kramdown会把单独的_识别为斜体标记，可在_config.yml中禁用该规则：

   kramdown:
     italic_angle: 0  # 关闭_作为斜体的解析逻辑
     parse_block_html: true
     parse_span_html: true
   

   重新构建页面，验证公式是否正常渲染。

2. 检查MathJax配置
   确认页面加载的MathJax脚本中，inlineMath包含['$', '$']：

   <script type="text/javascript" id="MathJax-script" async
     src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
   </script>
   <script>
     MathJax = {
       tex: {
         inlineMath: [['$', '$'], ['\\(', '\\)']]
       }
     };
   </script>
   

   若配置中缺少$对，MathJax只会识别\(...\)格式的行内公式。

3. 验证LaTeX语法与转义问题

   • 将异常公式复制到MathJax在线验证工具，确认LaTeX语法本身无错误。
   • 检查公式中的反斜杠：Markdown可能会转义单个\，导致MathJax无法识别命令，可尝试用双反斜杠\\bar、\\bullet测试（注意Jekyll可能会再次转义，需本地构建验证）。

4. 查看渲染后的HTML源码
   打开异常页面，查看公式部分的HTML：

   • 若$被转义为$，说明Markdown解析器提前处理了特殊字符，需调整解析配置。
   • 若公式内容被包裹在<em>标签中，说明_被识别为斜体标记，需禁用Kramdown的斜体解析。

5. 本地构建测试
   运行bundle exec jekyll serve在本地构建页面，对比本地与GitHub Pages的渲染结果，排除服务器端的特殊配置差异。

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