Jekyll Mermaid Integration Tutorial

By Amr

Estimated reading time: 6 minutes

Edit on GitHub

Jekyll Mermaid Integration Tutorial

Complete tutorial for integrating Mermaid diagrams in Jekyll sites with GitHub Pages support.

Overview

This tutorial covers the complete integration of Mermaid diagrams in Jekyll sites, including both the jekyll-mermaid plugin approach and custom implementation for GitHub Pages compatibility.

Two Implementation Approaches

Best for: Local development, when you control the Jekyll build process.

Configuration:

# _config.yml
plugins:
  - jekyll-mermaid

mermaid:
  src: 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js'

Usage:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Try Again]


### 2. Custom Implementation (GitHub Pages Compatible)

**Best for:** GitHub Pages, when you need full control over the implementation.

**Configuration:**
```yaml
# _config.yml
plugins:
  - jekyll-mermaid  # Still needed for configuration

mermaid:
  src: 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js'

Include File: _includes/components/mermaid.html

<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', function() {
    mermaid.initialize({
      startOnLoad: true,
      theme: 'forest'
    });
  });
</script>

Head Include: _includes/core/head.html


  <!--
  ===================================================================
  MERMAID DIAGRAM INTEGRATION
  ===================================================================
  
  File: mermaid.html
  Path: _includes/components/mermaid.html
  Purpose: Load and initialize Mermaid.js for diagram rendering
  
  Usage:
  - Set 'mermaid: true' in page front matter
  - Use <div class="mermaid">...</div> syntax in content
  - Supports all Mermaid diagram types (flowcharts, sequence, gantt, etc.)
  
  Configuration:
  - Latest stable version via CDN
  - Forest theme for dark mode compatibility
  - Initialized on document ready
  
  Documentation:
  - https://mermaid.js.org/
  - https://github.com/mermaid-js/mermaid
  ===================================================================
-->

<!-- Load Mermaid.js from CDN (latest stable version) -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>

<!-- Initialize Mermaid with custom configuration -->
<script>
  document.addEventListener('DOMContentLoaded', function() {
    mermaid.initialize({
      startOnLoad: true,
      theme: 'forest',  // Options: default, forest, dark, neutral, base
      themeVariables: {
        primaryColor: '#007bff',
        primaryTextColor: '#fff',
        primaryBorderColor: '#0056b3',
        lineColor: '#6c757d',
        secondaryColor: '#6c757d',
        tertiaryColor: '#f8f9fa'
      },
      flowchart: {
        useMaxWidth: true,
        htmlLabels: true,
        curve: 'basis'
      },
      sequence: {
        diagramMarginX: 50,
        diagramMarginY: 10,
        actorMargin: 50,
        width: 150,
        height: 65,
        boxMargin: 10,
        boxTextMargin: 5,
        noteMargin: 10,
        messageMargin: 35,
        mirrorActors: true,
        bottomMarginAdj: 1,
        useMaxWidth: true
      },
      gantt: {
        titleTopMargin: 25,
        barHeight: 20,
        barGap: 4,
        topPadding: 50,
        leftPadding: 75,
        gridLineStartPadding: 35,
        fontSize: 11,
        numberSectionStyles: 4,
        axisFormat: '%Y-%m-%d'
      }
    });
    console.log('Mermaid.js initialized successfully');
  });
</script>

<!-- FontAwesome for Mermaid icon support (optional) -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css" crossorigin="anonymous">

<!-- Custom CSS for Mermaid diagrams -->
<style>
  .mermaid {
    text-align: center;
    margin: 2rem auto;
    background-color: transparent;
  }
  
  /* Ensure diagrams are responsive */
  .mermaid svg {
    max-width: 100%;
    height: auto;
  }
  
  /* Dark mode compatibility */
  @media (prefers-color-scheme: dark) {
    .mermaid {
      filter: brightness(0.9);
    }
  }
</style>

Usage:

<div class="mermaid">
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Try Again]
</div>

Implementation Details

File Structure

_includes/
  └── components/
      └── mermaid.html          # Mermaid configuration
  └── core/
      └── head.html             # Conditional include

_config.yml                     # Plugin configuration

Page Front Matter

For custom implementation, add to your page front matter:

---
title: "My Page"
mermaid: true
---

Diagram Examples

Flowchart

<div class="mermaid">
graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[Car]
</div>

Sequence Diagram

<div class="mermaid">
sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!
</div>

Class Diagram

<div class="mermaid">
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
</div>

GitHub Pages Compatibility

Why Custom Implementation?

GitHub Pages has limitations on Jekyll plugins. While jekyll-mermaid works locally, it may not render diagrams on GitHub Pages due to:

  1. Plugin Restrictions: GitHub Pages only supports specific plugins
  2. Build Process: Different build environment
  3. Security Policies: Limited JavaScript execution

Solution: Hybrid Approach

Our implementation uses both approaches:

  1. Plugin Configuration: For local development and configuration
  2. Custom Include: For GitHub Pages compatibility
  3. Conditional Loading: Only loads when needed

Troubleshooting

Common Issues

Issue Solution
Diagrams not rendering Check mermaid: true in front matter
Plugin not working Verify jekyll-mermaid is in plugins list
GitHub Pages issues Use custom implementation with <div class="mermaid">
Styling problems Check theme configuration in mermaid.html

Testing

  1. Local Testing: Use bundle exec jekyll serve
  2. GitHub Pages: Push to repository and check live site
  3. Validation: Use Mermaid Live Editor

Best Practices

1. Choose the Right Approach

  • Local Development: Use jekyll-mermaid plugin
  • GitHub Pages: Use custom implementation
  • Both: Use hybrid approach (recommended)

2. Performance Optimization

  • Only load Mermaid on pages that need it
  • Use conditional loading with page.mermaid
  • Consider lazy loading for large diagrams

3. Maintenance

  • Keep Mermaid version updated
  • Test both local and GitHub Pages environments
  • Document any custom configurations

Resources

Next Steps: See the complete Mermaid guide for comprehensive examples and reference.