TechOverflow Logo
TechOverflow

如何在 Hugo 中包含 KaTeX 0.16（LaTeX 渲染）

English Deutsch 简体中文

本文展示如何在 Hugo 中包含最新版本的 KaTeX (0.16) 以渲染 LaTeX 数学公式。我们不从 CDN 包含它，主要是出于 GDPR 原因，但也因为从本地服务器加载更快。

我们将从 assets 文件夹包含 katex.min.js、auto-render.min.js、katex.min.css，从 static 文件夹包含 fonts（这样 Hugo 会添加整个目录）。

注意： 在 v0.162.0 之前的 Hugo 版本中，将文件从 node_modules 符号链接到 assets 和 static 文件夹是常见做法。然而，从 v0.162.0 开始，Hugo 出于安全原因拒绝 resources.Get 中的符号链接条目（CVE-2026-50135），因此模块挂载现在是正确的做法。

首先，通过 npm 安装 katex：

npm_install_katex.sh
npm install --save katex

然后，将模块挂载添加到你的 hugo.yaml 中，将 katex dist 目录挂载到 assets/vendor/katex，将字体挂载到 static/css/fonts：

hugo.yaml
module:
  mounts:
    - source: assets
      target: assets
    - source: static
      target: static
    - source: node_modules/katex/dist
      target: assets/vendor/katex
    - source: node_modules/katex/dist/fonts
      target: static/css/fonts

重要： 当你定义 module.mounts 时，所有默认挂载都会被替换 — 所以你必须如上所示显式重新挂载 assets 和 static。

现在创建 themes/your-theme/layouts/partials/katex.html：

katex_hugo_partial.html
<!-- Include library -->
<link rel="stylesheet" href="{{ (resources.Get "vendor/katex/katex.min.css").RelPermalink }}" />
<script defer src="{{ (resources.Get "vendor/katex/katex.min.js").RelPermalink }}"></script>
<!-- Include auto-render extension & render all KaTeX formulae !-->
<script defer src="{{ (resources.Get "vendor/katex/contrib/auto-render.min.js").RelPermalink }}" onload="renderMathInElement(document.body);"></script>

在 themes/your-theme/layouts/partials/footer.html 中，有条件地包含 partial：

katex_footer_partial.html
<!-- Include KaTeX if enabled in post-->
{{ if .Params.katex }}
    {{ partial "katex.html" . }}
{{ end }}

然后，在你的文章 .md 文件中，设置

katex_frontmatter.yaml
katex: true

在 frontmatter 中启用 KaTeX 渲染。

现在你可以添加如以下公式

katex_example_formula.tex
$$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

到你的文章中，看到它被 KaTeX 渲染：

$$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$
Check out similar posts by category: Hugo