Как подключить KaTeX 0.16 в Hugo (рендеринг LaTeX)

Этот пост показывает, как подключить последнюю версию KaTeX (0.16) в Hugo для рендеринга математических формул LaTeX. Мы не подключаем его из CDN в основном из-за GDPR, но также потому, что быстрее загружать его с локального сервера.

Мы подключим katex.min.js, auto-render.min.js, katex.min.css из папки assets и fonts из папки static (чтобы Hugo добавил всю директорию).

Примечание: В версиях Hugo до v0.162.0 общим подходом было создание символических ссылок на файлы из node_modules в папки assets и static. Однако, начиная с v0.162.0, Hugo отклоняет символические ссылки в resources.Get по соображениям безопасности (CVE-2026-50135), поэтому module mounts теперь являются правильным подходом.

Сначала установите katex через npm:

npm install --save katex

Затем добавьте module mounts в ваш hugo.yaml, чтобы примонтировать директорию katex dist в assets/vendor/katex и шрифты в static/css/fonts:

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:

<!-- 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:

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

Затем в вашем посте .md установите

katex: true

в frontmatter, чтобы включить рендеринг KaTeX.

Теперь вы можете добавить формулу, такую как

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

в ваш пост, чтобы увидеть её отрендеренной KaTeX: