问题 链接到标题

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

Hugo Coder 主题已内置 KaTeX 链接到标题

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

定界符 类型
$$...$$ 块级公式
$...$ 行内公式
\(...\) 行内公式
\[...\] 块级公式

激活方式 链接到标题

方式一：文章级启用（推荐） 链接到标题

在文章 frontmatter 中加一行：

math: true

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

方式二：站点级启用 链接到标题

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

[params]
  math = true

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

公式居左 链接到标题

默认 display math 居中：

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

若需居左，KaTeX 提供了原生 fleqn 模式。在主题的 math.html 中，renderMathInElement 调用加一个选项：

renderMathInElement(document.body, {
  delimiters: [
    {left: '$$', right: '$$', display: true},
    {left: '$', right: '$', display: false},
    {left: '\\(', right: '\\)', display: false},
    {left: '\\[', right: '\\]', display: true}
  ],
  fleqn: true    // ← 公式居左
});

不要直接修改主题文件（下次更新会被覆盖），在站点目录下创建同路径文件覆盖：

mkdir -p layouts/_partials/posts/
cp themes/hugo-coder/layouts/_partials/posts/math.html layouts/_partials/posts/
# 然后编辑 layouts/_partials/posts/math.html，加上 fleqn: true

Hugo 优先加载站点 layouts/ 下的文件，同名文件会覆盖主题中的对应文件。

公式效果 链接到标题

块级公式：

$$ \oint_S \mathbf{E} \cdot d\mathbf{A} = \frac{Q}{\varepsilon_0} $$

行内公式：质能方程 $E = mc^2$，勾股定理 $a^2 + b^2 = c^2$。

多行公式：

$$ \begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \ \nabla \cdot \mathbf{B} &= 0 \ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \ \nabla \times \mathbf{B} &= \mu_0 \mathbf{J} + \mu_0 \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \end{aligned} $$

踩坑记录 链接到标题

问题 原因 解决
公式仍然居中 CSS 覆盖 .katex-display 不够，内层 .katex 也有 text-align: center 用 KaTeX 官方 fleqn 选项
页面未显示公式 hugo.toml 未设 unsafe = true 添加 [markup.goldmark.renderer] unsafe = true
frontmatter 设了 math: true 无效 主题版本较旧或 math.html partial 路径不对 检查 layouts/_partials/posts/math.html 是否存在

总结 链接到标题

Hugo Coder 主题集成 KaTeX 很简单：frontmatter 加 math: true 即可。需要居左时覆盖主题的 math.html 加上 fleqn: true。所有配置不超过 10 行，零额外依赖。