Mermaid Diagrams in Jekyll
This guide covers everything you need to know about using Mermaid diagrams in your Jekyll site.
✅ GitHub Pages Compatible: Works with GitHub Pages without custom plugins!
Quick Start
1. Enable Mermaid on a Page
Add mermaid: true to your page’s front matter:
---
title: "My Page with Diagrams"
mermaid: true
---
2. Add a Diagram
Option A: Native Markdown Syntax (Recommended)
Use triple backticks with mermaid as the language:
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Success]
B -->|No| D[Try Again]
```
Option B: HTML Div Syntax
Use the <div class="mermaid"> syntax:
<div class="mermaid">
graph TD A[Start] --> B{Decision} B -->|Yes| C[Success] B -->|No| D[Try Again]
</div>
Result:
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Success]
B -->|No| D[Try Again]
Diagram Types
1. Flowcharts
Basic Flowchart:
graph LR
A[Input] --> B[Process]
B --> C{Valid?}
C -->|Yes| D[Success]
C -->|No| E[Error]
Directions:
TDorTB- Top to bottomBT- Bottom to topLR- Left to rightRL- Right to left
Node Shapes:
A[Rectangle]- RectangleA(Rounded)- Rounded edgesA{Diamond}- Diamond (decision)A((Circle))- Circle
2. Sequence Diagrams
sequenceDiagram
participant User
participant Browser
participant Server
participant Database
User->>Browser: Enter credentials
Browser->>Server: POST /login
Server->>Database: Verify credentials
Database-->>Server: User found
Server-->>Browser: Auth token
Browser-->>User: Login success
Arrow Types:
->- Solid line without arrow-->- Dotted line without arrow->>- Solid line with arrow-->>- Dotted line with arrow
3. Class Diagrams
classDiagram
class User {
+String name
+String email
+login()
+logout()
}
class Admin {
+String permissions
+manageUsers()
}
User <|-- Admin
User "1" --> "*" Post : creates
Relationships:
<|--- Inheritance*--- Compositiono--- Aggregation-->- Association
4. State Diagrams
stateDiagram-v2
[*] --> Draft
Draft --> Review: Submit
Review --> Approved: Accept
Review --> Draft: Reject
Approved --> Published: Publish
Published --> [*]
5. Entity Relationship Diagrams
erDiagram
USER ||--o{ POST : creates
USER ||--o{ COMMENT : writes
POST ||--o{ COMMENT : has
USER {
int id PK
string username
string email
}
POST {
int id PK
int user_id FK
string title
text content
}
6. Gantt Charts
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Planning
Requirements :a1, 2025-01-01, 7d
Design :a2, after a1, 5d
section Development
Frontend :a3, after a2, 14d
Backend :a4, after a2, 14d
7. Pie Charts
pie title Website Traffic Sources
"Direct" : 42.5
"Search Engines" : 28.3
"Social Media" : 18.7
"Referral" : 10.5
8. Git Graphs
gitGraph
commit id: "Initial commit"
branch develop
checkout develop
commit id: "Add feature"
branch feature
checkout feature
commit id: "Implement feature"
checkout develop
merge feature
checkout main
merge develop tag: "v1.0.0"
9. Journey Diagrams
journey
title User Shopping Experience
section Discovery
Search product: 5: User
View results: 4: User
section Evaluation
Read reviews: 3: User
Compare prices: 4: User
section Purchase
Add to cart: 5: User
Checkout: 3: User
Styling and Customization
Theme Options
The Mermaid theme is configured in _includes/components/mermaid.html:
mermaid.initialize({
theme: "forest", // Options: default, forest, dark, neutral, base
themeVariables: {
primaryColor: "#007bff",
primaryTextColor: "#fff",
},
});
Custom Colors
graph TD
A[Start]:::greenClass --> B[Process]:::blueClass
B --> C[End]:::redClass
classDef greenClass fill:#9f6,stroke:#333,stroke-width:2px
classDef blueClass fill:#69f,stroke:#333,stroke-width:2px
classDef redClass fill:#f96,stroke:#333,stroke-width:2px
Icons (FontAwesome)
graph TD
A[fa:fa-home Home]
B[fa:fa-user User]
C[fa:fa-cog Settings]
A --> B
A --> C
Advanced Features
Links and Interactivity
graph LR
A[Homepage]
B[About]
C[Contact]
click A "https://example.com" "Visit Homepage"
click B "https://example.com/about" "About Us"
Subgraphs
graph TB
subgraph Frontend
A[React] --> B[Components]
end
subgraph Backend
C[API] --> D[Database]
end
B --> C
Comments
<div class="mermaid">graph TD A --> B %% This is a comment B --> C</div>
Troubleshooting
Common Issues
| Issue | Solution |
|---|---|
| Diagram not rendering | Add mermaid: true to front matter |
| Syntax error | Validate at mermaid.live |
| Diagram too small | Diagrams are responsive by default |
| Wrong colors | Check theme setting in mermaid.html |
| Console errors | Check browser DevTools for JavaScript errors |
Testing Your Diagrams
- Validate Syntax: Use Mermaid Live Editor
- Check Front Matter: Ensure
mermaid: trueis present - Browser Console: Look for JavaScript errors
- Clear Cache: Force refresh (Cmd+Shift+R / Ctrl+Shift+R)
Best Practices
1. Keep Diagrams Simple
<!-- ✅ Good - Clear and focused -->
<div class="mermaid">graph LR A[Input] --> B[Process] --> C[Output]</div>
<!-- ❌ Avoid - Too complex -->
<div class="mermaid">graph TD A --> B --> C --> D --> E --> F --> G --> H</div>
2. Use Descriptive Labels
<!-- ✅ Good -->
<div class="mermaid">
graph TD A[User Login] --> B{Credentials Valid?} B -->|Yes| C[Dashboard] B
-->|No| D[Error Message]
</div>
3. Add Comments for Complex Diagrams
<div class="mermaid">
graph TD %% Main authentication flow A[Start] --> B{Auth Type} %% OAuth path B
-->|OAuth| C[OAuth Provider] %% Basic auth path B -->|Basic| D[Verify
Credentials]
</div>
Resources
Official Documentation
- Website: mermaid.js.org
- GitHub: mermaid-js/mermaid
- Live Editor: mermaid.live
Learning Path
- Start Here: This guide covers the basics
- Practice: Use mermaid.live to test diagrams
- Reference: Keep this page bookmarked for syntax
- Master: Read Official Docs for advanced features
Implementation Details
File Structure
_includes/
└── components/
└── mermaid.html # Mermaid configuration
└── core/
└── head.html # Conditional include
_config.yml # Plugin configuration
Configuration
The implementation uses:
- Mermaid v10 - Latest stable version
- Conditional Loading - Only loads when
mermaid: true - Forest Theme - Optimized for dark mode
- FontAwesome Support - Icons in diagrams
- Responsive Design - Scales automatically
Happy Diagramming! 📊
This implementation is fully functional and GitHub Pages compatible.