45. 【GitHub Page】🧩 GitHub Pagesで数式とMermaidを同時に表示する最小テンプレ

topics: [“GitHubPages”, “Jekyll”, “MathJax”, “Mermaid”, “Qiita”]

Qiita が求めるのは、
「そのまま書けて、実際に動く構成」です。

それでいて、
GitHub Pages 上でも崩れずに表示されることが重要です。

本記事では、
MathJax（数式）と Mermaid（図）を
同時に安定表示するための最小テンプレ構成をまとめます。

🎯 目的

以下を満たす構成を作ります。

🗂 構成（最小）

必要なファイルは、以下の 4 つだけです。

_config.yml
_layouts/default.html
_includes/head.html
articles/*.md

📌
余計なプラグインやビルド設定は不要です。

🧱 default.html

Markdown 本文を表示するための
最小のレイアウトです。

<!DOCTYPE html>
<html lang="ja">
<head>
  {% include head.html %}
</head>
<body>
  <main class="page-content">
    <article>
      {{ content }}
    </article>
  </main>
</body>
</html>

📌 ポイント

🧠 head.html（MathJax + Mermaid）

数式と図を同時に動かす 中核部分です。

<script>
  window.MathJax = {
    tex: {
      inlineMath: [['$', '$']],
      displayMath: [['$$', '$$']]
    }
  };
</script>
<script defer src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>

<script defer src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    document.querySelectorAll("code.language-mermaid").forEach(code => {
      const div = document.createElement("div");
      div.className = "mermaid";
      div.textContent = code.textContent;
      code.parentElement.replaceWith(div);
    });
    mermaid.initialize({ startOnLoad: false });
    mermaid.run();
  });
</script>

📌 ポイント

✏️ Markdown 記述例（そのまま使える）

以下は、Qiita と 完全に同じ書き方です。

インライン数式：$V = IR$

\[\mathbf{A}= \begin{bmatrix} 0 & 1 \\ - \omega_n^2 & -2 \zeta \omega_n \end{bmatrix}\] 
flowchart TD
  A[入力 V] --> B[制御器]
  B --> C[プラント]
  C --> D[出力 I]

👉 数式・行列・Mermaid 図が
すべて同一ページで問題なく描画されます。

🔍 動作確認デモ

このテンプレ構成で
実際に表示されているページはこちらです。

📌
「本当に動いているか」を
実ページで確認できるリンクを置くのが重要です。

⚠️ 注意点（安定運用のために）

📝 まとめ