给 Hugo 博客加上数学公式渲染

Wed, 08 Jul 2026 19:17:00 +0800

问题链接到标题

macOS 下 Markdown 数学公式正确转 PDF讲了怎么把 Markdown 导出为带公式的 PDF。但博客本身也要能显示公式，不能让读者看到一坨 $$...$$ 原始代码。

主题目录下已有 layouts/_partials/posts/math.html，加载 KaTeX v0.16.4（CSS + JS + auto-render），支持四种定界符：

在文章 frontmatter 中加一行：

math: true

当前文章的公式就是通过这种方式渲染的。只对单篇文章生效，不拖慢其他页面。

在 hugo.toml 的 [params] 中添加：

[params]
  math = true

所有页面都会加载 KaTeX，方便但会增加不必要的请求。

Wed, 08 Jul 2026 18:48:00 +0800

Markdown 里用 $$ 写好的 LaTeX 数学公式：

$$
\nabla \cdot \mathbf{E} = \frac{\rho}{\varepsilon_0}
$$

期望渲染效果：

$$ \nabla \cdot \mathbf{E} = \frac{\rho}{\varepsilon_0} $$

但转 PDF 时，要么公式显示为原始代码，要么中文字体缺失乱码。本文记录 macOS 下的可行方案。

brew install basictex
pandoc file.md -o file.pdf --pdf-engine=xelatex -V mainfont='PingFang SC'

公式渲染效果没问题，但输出风格偏 TeX 传统——标题字体、表格样式、公式间距都与现代文档有明显差异，不够美观。

核心思路：用 Pandoc 生成带 MathJax CDN 的 HTML，再用 Puppeteer（Headless Chrome）渲染出 PDF。输出样式完全由 CSS 控制。