\\[Hugo] でOGP用のメタタグを設定する方法の紹介。

はじめに

Hugo で数式を綺麗に表示させたいときの手順。

テーマは PaperMod を利用。

1. config.toml の設定

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

[params]
  math = false   # 全体では無効。記事ごとに math: true を付けて有効化する運用
  • unsafe = true は KaTeX の <script> を通すために必須。
  • サイト全体で常に数式を使うなら math = true にしてもOK。

2. 記事ごとのフロントマター

数式を使う記事だけ、以下を追加：

---
title: "サンプル記事"
math: true
---

3. extend_head.html を作成

layouts/partials/extend_head.html を作成し、KaTeX の読み込みを条件付きで追加：

{{ if .Params.math }}
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"></script>
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js"></script>
  <script>
    (function () {
      function run() {
        // 本文ターゲット（PaperModの差異を吸収）
        var root =
          document.querySelector(".post-content") ||
          document.querySelector(".content") ||
          document.querySelector("article") ||
          document.body;

        window.renderMathInElement(root, {
          delimiters: [
            { left: "$$", right: "$$", display: true },
            { left: "\\[", right: "\\]", display: true },
            { left: "\\(", right: "\\)", display: false },
            { left: "$",  right: "$",  display: false } // 混在対策（徐々に外してOK）
          ],
          ignoredTags: ["script","noscript","style","textarea","pre","code"],
          strict: "warn"
        });
      }

      // renderMathInElement が来るまで待つ（最大 ~3秒くらい）
      function waitAndRun(deadlineMs) {
        var t0 = Date.now();
        (function loop() {
          if (window.renderMathInElement) {
            // DOM の準備も待つ
            if (document.readyState === "loading") {
              document.addEventListener("DOMContentLoaded", run, { once: true });
            } else {
              run();
            }
          } else if (Date.now() - t0 < (deadlineMs || 3000)) {
            setTimeout(loop, 50);
          } else {
            console.warn("KaTeX auto-render が見つからず実行をスキップしました");
          }
        })();
      }

      // アイドル時 or すぐ
      if ("requestIdleCallback" in window) requestIdleCallback(function(){ waitAndRun(); });
      else waitAndRun();
    })();
  </script>

{{ end }}

4. baseof.html に差し込み

PaperMod の baseof.html が上書きされている場合、</head> の直前に以下を追加：

{{/* KaTeX hook */}}
{{ partial "extend_head.html" . }}

5. 数式記法の推奨

  • インライン：\( ... \)
  • ブロック：$$ ... $$ または \[ ... \]

例：

インライン数式: \( p^T A q \)

ブロック数式:
$$
E(C1) = ap + c(1-p), \\
E(C2) = bp + d(1-p)
$$

使用例

$$ E(C1) = ap + c(1-p), \ E(C2) = bp + d(1-p) $$

6. 軽量化ポイント

  • 記事ごとの math: true で不要ページは KaTeX を読み込まない。
  • document.querySelector(".post-content") で本文だけを走査。
  • $...$ より \( ... \) / \[ ... \] を優先すると誤爆が少なく軽い。
  • 初回だけ CDN 読み込みで重い → 以後はキャッシュで軽快。
  • 必要なら KaTeX を static/vendor/katex/ に置いて自前ホスト。

7. CSS 調整（任意）

assets/css/extended/math.css に以下を追加すると見やすい：

.post-content .katex { font-size: 1.06em; }
.post-content .katex-display {
  margin: 0.8rem 0 1rem;
  overflow-x: auto;
  padding: .25rem 0;
}
li > .katex-display { margin-left: 0; }

まとめ

  • Hugo + PaperMod で数式を表示するには Goldmark unsafe を有効化し、KaTeX を partial で差し込む。
  • math: true を front matter に付ける運用で、不要ページを軽くできる。
  • インラインは \( ... \)、ブロックは $$ ... $$ か \[ ... \] を推奨。