No flag needed! Auto-detection handles this
🎯 Mermaid diagrams are automatically detected and rendered. No configuration needed!
Overview¶
The zer0-mistakes theme includes automatic Mermaid diagram detection. Simply use standard markdown code fences - the system handles everything else automatically.
Quick Start¶
- Write your diagram using code fences:
```mermaid
graph TD;
A[Start] --> B{Is it working?};
B -->|Yes| C[Great!];
B -->|No| D[Check console];
```
- That's it! No front matter, no configuration needed.
How It Works¶
Auto-Detection Magic ✨¶
The theme automatically:
- Scans page content for ``mermaid code blocks
- **Detects HTML elements** with
Performance Benefits 🚀¶
- On-demand loading - Library only loads on pages with diagrams
- ~200KB Mermaid.js only downloaded when needed
- Fast CDN delivery with global caching
- Zero impact on pages without diagrams
All Diagram Types Supported¶
1. Flowcharts¶
```mermaid
graph TD;
A[Start] --> B{Decision};
B -->|Yes| C[Action 1];
B -->|No| D[Action 2];
C --> E[End];
D --> E;
```
2. Sequence Diagrams¶
```mermaid
sequenceDiagram
participant A as Alice
participant B as Bob
A->>B: Hello Bob, how are you?
B-->>A: Great!
A-)B: See you later!
```
3. Class Diagrams¶
```mermaid
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+String breed
+bark()
}
Animal <|-- Dog
```
4. State Diagrams¶
```mermaid
stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
```
5. Entity Relationship Diagrams¶
```mermaid
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ ORDER_LINE : contains
PRODUCT ||--o{ ORDER_LINE : "ordered in"
```
6. Gantt Charts¶
```mermaid
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Planning :done, plan1, 2025-01-01, 2025-01-15
Development :active, dev1, 2025-01-16, 2025-02-15
section Phase 2
Testing : test1, 2025-02-16, 2025-03-01
Deployment : deploy1, 2025-03-02, 2025-03-15
```
7. Pie Charts¶
8. Git Graphs¶
```mermaid
gitgraph
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
```
9. Journey Diagrams¶
```mermaid
journey
title User Journey
section Discovery
Visit website: 5: User
Browse products: 4: User
section Purchase
Add to cart: 3: User
Checkout: 5: User
Payment: 4: User
```
Advanced Features¶
FontAwesome Icons¶
```mermaid
graph TD;
A[fa:fa-home Home] --> B[fa:fa-user User];
B --> C[fa:fa-cog Settings];
C --> D[fa:fa-check Success];
```
Custom Styling¶
```mermaid
graph TD;
A[Start] --> B{Decision};
B -->|Yes| C[Action];
classDef startNode fill:#e1f5fe;
classDef decisionNode fill:#fff3e0;
classDef actionNode fill:#e8f5e8;
class A startNode;
class B decisionNode;
class C actionNode;
```
Subgraphs¶
```mermaid
graph TB
subgraph "Frontend"
A[React App]
B[Vue App]
end
subgraph "Backend"
C[API Server]
D[Database]
end
A --> C
B --> C
C --> D
```
Troubleshooting¶
Diagrams Not Rendering? 🔧¶
- Check browser console for JavaScript errors
- Validate syntax at mermaid.live
- Ensure code fence uses ```mermaid (not mermade, mermaud, etc.)
- Check network tab to verify Mermaid.js loaded
- Verify theme is using zer0-mistakes v0.5.0+
Common Issues¶
Issue: Diagrams show as code blocks - Solution: Check for typos in ```mermaid fence - Solution: Ensure theme is up to date
Issue: Library not loading - Solution: Check console for CDN errors - Solution: Verify internet connection
Issue: Styling looks wrong - Solution: Check for CSS conflicts - Solution: Verify theme compatibility
Manual Override¶
If you need to force Mermaid loading (rare cases):
Migration Guide¶
Old Approach (Deprecated)¶
New Approach (Automatic)¶
Your old posts still work (backwards compatible), but you can now remove the mermaid: true flags.
Performance Comparison¶
Before (Manual Configuration)¶
- ❌ Mermaid.js loaded site-wide if any post had
mermaid: true - ❌ Manual flag management required
- ❌ Easy to forget configuration
- ❌ Poor developer experience
After (Auto-Detection)¶
- ✅ Mermaid.js loads only on pages with diagrams
- ✅ Zero configuration required
- ✅ Impossible to forget
- ✅ Better developer experience
- ✅ Improved performance
Best Practices¶
- Use standard markdown fences - ```mermaid blocks work everywhere
- Keep diagrams simple - Complex diagrams may render slowly
- Test locally first - Validate syntax before publishing
- Use meaningful labels - Make diagrams self-documenting
- Consider mobile - Ensure diagrams are readable on small screens
Integration with Jekyll¶
GitHub Pages Compatibility¶
The auto-detection works perfectly with GitHub Pages: - No server-side plugins required - Client-side detection after Jekyll renders HTML - CDN loading ensures global availability - Kramdown processes code fences correctly
Theme Integration¶
The zer0-mistakes theme handles everything:
- Automatic detection in _includes/components/mermaid-auto.html
- Conditional loading in _includes/core/head.html
- Responsive styling and dark mode support
- Error handling and console logging
Resources¶
- Mermaid Live Editor - Test your diagrams
- Mermaid Documentation - Complete syntax reference
- Theme Documentation - Full theme guide
- Migration Guide - Upgrading from manual configuration
AI Instructions¶
Setting up Jekyll to use Mermaid diagrams is now incredibly simple with the zer0-mistakes theme:
1. Use the Theme¶
Ensure your _config.yml includes:
2. Write Diagrams¶
Simply use markdown code fences:
3. That's It!¶
No configuration, no front matter, no setup required. The theme automatically detects and renders your diagrams.
Troubleshooting¶
If diagrams don't render: 1. Check browser console for errors 2. Verify theme version (v0.5.0+) 3. Test syntax at mermaid.live 4. Ensure proper code fence syntax
The auto-detection feature makes Mermaid integration seamless and eliminates common configuration errors.