GitHub Pages Doesn’t Render Mermaid (But Can Be Fixed)

The Problem

GitHub.com shows mermaid diagrams beautifully when viewing markdown files. GitHub Pages (Jekyll) does not. Your diagrams appear as code blocks.

Why

• GitHub.com has native mermaid support (added recently)
• GitHub Pages uses Jekyll which doesn’t include mermaid.js
• The minimal theme (and most themes) don’t include it by default

The Fix

Create _layouts/default.html that:

1. Extends your theme’s default layout
2. Includes mermaid.js from CDN
3. Initializes it with startOnLoad: true

Key lines:

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
  mermaid.initialize({
    startOnLoad: true,
    theme: 'default'
  });
</script>

What Doesn’t Work

• Adding plugins to _config.yml (GitHub Pages only allows approved plugins)
• Using jekyll-mermaid gem (not in approved list)
• Config-only solutions (you need actual HTML/JavaScript)

The Lesson

GitHub’s markdown rendering and GitHub Pages markdown rendering are different systems. What works in repo preview may not work on Pages. Always test the actual Pages site.

Applied In

• auto-slacker: _layouts/default.html created 2025-10-26
• All subdirectory READMEs with mermaid diagrams now render correctly