Mermaid Auto-Detection Migration Guide¶

What Changed? 🎯¶

The zer0-mistakes theme now automatically detects Mermaid diagrams. You no longer need mermaid: true in front matter!

Before (Manual Configuration)¶

---
title: My Post
mermaid: true  # Required for diagrams to render
---

After (Auto-Detection)¶

---
title: My Post
# No flag needed! Auto-detection handles this
---

Action Required¶

None! Your existing posts still work (backwards compatible).

The theme automatically: - ✅ Detects ```mermaid code blocks in your content - ✅ Loads Mermaid.js library on-demand - ✅ Renders diagrams with optimized settings - ✅ Maintains all existing functionality

Optional Cleanup¶

You can remove mermaid: true from front matter to clean up your posts:

---
title: My Post
- mermaid: true
---

Benefits of Cleanup¶

🎯 Better DX - impossible to forget configuration
⚡ Performance - library loads only when needed
🔧 Less maintenance - fewer front matter fields
📝 Cleaner content - standard markdown syntax

Migration Steps¶

Step 1: Update Theme¶

Ensure you're using zer0-mistakes v0.5.0+:

# _config.yml
remote_theme: "bamr87/zer0-mistakes"

Step 2: Test Your Diagrams¶

Start local Jekyll server:
```
bundle exec jekyll serve --port 4002
```
Visit pages with Mermaid diagrams
Check browser console for "Mermaid diagrams detected" message
Verify all diagrams render correctly

Step 3: Remove Front Matter Flags (Optional)¶

Search for files with mermaid: true:

grep -r "mermaid: true" pages/

Remove the flag from each file:

---
title: My Post
- mermaid: true
---

Step 4: Update Documentation¶

Update any internal documentation that mentions the old approach:

Remove references to mermaid: true requirement
Update examples to show auto-detection
Add notes about performance benefits

Technical Details¶

How Auto-Detection Works¶

Content Scanning: Theme scans page content for ```mermaid blocks
Dynamic Loading: Mermaid.js loads from CDN only when needed
Automatic Rendering: Diagrams render with optimized theme settings
Performance: Zero impact on pages without diagrams

Detection Methods¶

The theme detects Mermaid content through: - ``mermaid code blocks in markdown -

HTML elements
-

mermaid: true` front matter (backwards compatibility)

Performance Impact¶

Before: - Mermaid.js loaded site-wide if any post had mermaid: true - ~200KB library loaded on every page

After: - Mermaid.js loads only on pages with diagrams - Zero impact on pages without diagrams - Improved site performance

Troubleshooting¶

Diagrams Not Rendering?¶

Check theme version: Ensure zer0-mistakes v0.5.0+
Browser console: Look for "Mermaid diagrams detected" message
Syntax validation: Test at mermaid.live
Network tab: Verify Mermaid.js loads from CDN

Common Issues¶

Issue: Old posts with mermaid: true don't work - Solution: Update theme to v0.5.0+ - Solution: Check browser console for errors

Issue: New posts without mermaid: true don't work - Solution: Ensure theme is updated - Solution: Check for syntax errors in diagrams

Issue: Performance seems slower - Solution: This shouldn't happen - auto-detection is faster - Solution: Check for multiple Mermaid.js loads in network tab

Rollback Plan¶

If you need to rollback to manual configuration:

Revert theme: Use zer0-mistakes v0.4.0
Add flags: Add mermaid: true to all posts with diagrams
Test: Verify diagrams render correctly

Benefits Summary¶

Developer Experience¶

✅ Zero configuration required
✅ Impossible to forget setup
✅ Standard markdown syntax
✅ Better error messages

Performance¶

✅ On-demand loading only
✅ Faster page loads
✅ Reduced bandwidth usage
✅ Better caching

Maintenance¶

✅ Fewer front matter fields
✅ Cleaner content files
✅ Less configuration drift
✅ Easier onboarding

Support¶

If you encounter issues during migration:

Check documentation: Mermaid Guide
Test syntax: Mermaid Live Editor
Browser console: Look for error messages
Theme version: Ensure v0.5.0+ is installed

Next Steps¶

Update theme to zer0-mistakes v0.5.0+
Test diagrams on local development server
Remove flags from front matter (optional)
Update documentation to reflect new approach
Enjoy the improved developer experience!

This migration guide is part of the zer0-mistakes theme v0.5.0 release. For more information, visit the theme documentation.