45. 【GitHub Pages】🧩 Minimal Template to Render Math and Mermaid Together on GitHub Pages (Jekyll)

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

What Qiita really expects is a setup that is:

“Written as-is, and actually works.”

And yet,
everything must render correctly on GitHub Pages as well.

In this article, we summarize a minimal and stable template
to render MathJax (math) and Mermaid (diagrams)
together on the same page.

🎯 Goal

We aim to achieve the following:

🗂 Minimal Structure

Only the following four files are required.

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

📌
No extra plugins or build settings are required.

🧱 default.html

This is the minimal layout for rendering Markdown content.

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

📌 Notes

🧠 head.html (MathJax + Mermaid)

This is the core of the entire setup.

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

📌 Notes

✏️ Markdown Writing Example (As-Is)

The following works exactly the same as on Qiita.

Inline math: $V = IR$

\[\mathbf{A}= \begin{bmatrix} 0 & 1 \\ - \omega_n^2 & -2 \zeta \omega_n \end{bmatrix}\] 
flowchart TD
  A[Input V] --> B[Controller]
  B --> C[Plant]
  C --> D[Output I]

👉 Math, matrices, and Mermaid diagrams
are all rendered correctly on a single page.

🔍 Live Demo (Rendered Output)

You can see the actual rendered result here:

📌
Always include a real, working demo link
to prove that the setup actually works.

⚠️ Notes for Stable Operation

📝 Summary