如何在Jekyll搭建的GitHub Pages中插入MathJax脚本实现LaTeX渲染？

云原生阿岚

2026-6-25

解决Jekyll + GitHub Pages集成MathJax渲染LaTeX公式的问题

修正_config.yml配置
在你的_config.yml中补充完整Kramdown的数学引擎配置，替换原来的简单设置：
```
markdown: kramdown
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge
```
仅设置mathjax: true不足以让Kramdown正确识别并传递LaTeX公式给MathJax。
调整MathJax脚本与配置
在你的_includes/head.html或_layouts/base.html的<head>标签内，添加MathJax的配置脚本再加载核心库，确保分隔符匹配：
```
<script>
  MathJax = {
    tex: {
      inlineMath: [['\\(', '\\)']],
      displayMath: [['\\[', '\\]']]
    }
  };
</script>
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
```
这段配置明确告诉MathJax使用\( \)作为行内公式分隔符，\[ \]作为块级公式分隔符，避免与Jekyll的转义逻辑冲突。
避免Jekyll转义公式中的反斜杠
如果你在Markdown中写的公式被Jekyll转义（比如变成\(x)而不是\(x\)），可以用Jekyll的raw标签包裹公式：
```
{% raw %}\(x + y = z\){% endraw %}
```
这样Jekyll会跳过对公式内容的处理，直接传递给MathJax。
清理本地缓存重新构建
本地测试时，执行以下命令清理旧缓存并重新生成站点：
```
bundle exec jekyll clean && bundle exec jekyll serve
```
避免旧的编译结果干扰测试。
检查浏览器控制台排查问题
打开浏览器开发者工具（F12），切换到Console标签查看是否有MathJax加载报错，比如CDN链接失效、脚本加载顺序问题等。如果CDN链接无法访问，可以替换为兼容性更好的MathJax v2版本链接：
```
<script id="MathJax-script" async src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
```