Testing Mermaid Diagrams in Blog Posts

This post tests the Mermaid diagram functionality in our blog. Mermaid allows us to create diagrams and flowcharts using simple text syntax.

Simple Flowchart

Here's a basic flowchart showing a decision process:

Code for this diagram:

1```mermaid
2flowchart TD
3    A[Start] --> B{Is it working?}
4    B -->|Yes| C[Great!]
5    B -->|No| D[Debug]
6    D --> E[Fix Issue]
7    E --> B
8    C --> F[End]
9```

Git Workflow Diagram

This diagram shows our new branch protection workflow:

Sequence Diagram

Here's how the fork management process works:

Code for this diagram:

1```mermaid
2sequenceDiagram
3    participant U as User
4    participant F as Fork
5    participant M as Main Repo
6    participant CI as GitHub Actions
7
8    U->>F: Create fork
9    U->>F: Add personal content
10    U->>F: Make improvements
11    F->>M: Create pull request
12    M->>CI: Run automated checks
13    CI->>M: Validation results
14    M->>M: Review and selective merge
15    M->>F: Provide feedback
16```

Class Diagram

The architecture of our blog system:

Pie Chart

Distribution of our documentation types:

State Diagram

The lifecycle of a blog post:

Journey Map

User experience with our blog template:

C4 Architecture Diagrams

System Context Diagram

This shows our blog template in the context of its environment:

Code for this diagram:

1```mermaid
2graph TB
3    User[👤 Blog Users] --> Blog[Next.js Blog Template]
4    Developer[👨‍💻 Developers] --> Blog
5
6    Blog --> Cloudflare[☁️ Cloudflare Workers]
7    Blog --> GitHub[📦 GitHub Repository]
8    Blog --> CDN[🌍 Global CDN]
9
10    subgraph "External Systems"
11        Cloudflare
12        GitHub
13        CDN
14    end
15
16    subgraph "Next.js Blog Template"
17        NextJS[Next.js 15 App]
18        MDX[MDX Content]
19        MUI[Material-UI]
20        Mermaid[Mermaid Diagrams]
21    end
22
23    style Blog fill:#e1f5fe
24    style Cloudflare fill:#fff3e0
25    style GitHub fill:#f3e5f5
26    style NextJS fill:#e8f5e8
27    style MDX fill:#fff8e1
28    style MUI fill:#fce4ec
29    style Mermaid fill:#e8eaf6
30```

Container Diagram

This shows the main containers within our blog system:

These diagrams should automatically adapt to both light and dark themes. The Mermaid component uses the current Material-UI theme to configure colors and styling.

Features Tested:

✅ Flowcharts with decision nodes
✅ Git graphs with branches and merges
✅ Sequence diagrams with multiple participants
✅ Class diagrams with relationships
✅ Pie charts with data visualization
✅ State diagrams with transitions
✅ Journey maps with emotional states
✅ Theme-aware rendering (light/dark mode)
✅ Responsive design for mobile devices

Code Example

For comparison, here's regular code syntax highlighting:

1// Regular code block (not Mermaid)
2function generateMermaidId() {
3  return `mermaid-${Math.random().toString(36).substr(2, 9)}`;
4}
5
6console.log('This should be syntax highlighted, not rendered as a diagram');

And here's some TypeScript:

1interface MermaidProps {
2  chart: string;
3  id?: string;
4}
5
6const MermaidComponent: React.FC<MermaidProps> = ({ chart, id }) => {
7  // Component implementation
8  return <div>Mermaid diagram here</div>;
9};

Mermaid Resources and Documentation

Official Documentation

Main Documentation: mermaid.js.org
Live Editor: mermaid.live - Test your diagrams online
Syntax Reference: Flowchart Syntax
All Diagram Types: Diagram Syntax

Quick Reference

Flowcharts: flowchart TD or graph TB
Sequence Diagrams: sequenceDiagram
Class Diagrams: classDiagram
State Diagrams: stateDiagram-v2
Git Graphs: gitGraph
Pie Charts: pie title "Chart Title"
Journey Maps: journey

Tips for Better Diagrams

Test First: Always test complex diagrams in mermaid.live
Keep It Simple: Don't overcrowd diagrams with too many elements
Use Colors: Add style commands for better visual hierarchy
Mobile Friendly: Consider how diagrams look on small screens
Meaningful Labels: Use descriptive text for nodes and connections

How to Use Mermaid in Your Blog Posts

Step 1: Write Your Diagram

Create your diagram using Mermaid syntax in a code block:

1```mermaid
2flowchart LR
3    A[Write Post] --> B[Add Diagram]
4    B --> C[Test in mermaid.live]
5    C --> D[Publish]
6```

Step 2: Test Online

Before publishing, test your diagram at mermaid.live to ensure it renders correctly.

Step 3: Add to Your Post

Simply paste the code block into your .mdx file and it will automatically render as a visual diagram.

Common Use Cases

Process Flows: Show step-by-step processes
System Architecture: Visualize component relationships
User Journeys: Map user experience flows
Decision Trees: Show decision-making processes
Git Workflows: Illustrate branching strategies
Data Flows: Show how data moves through systems

Conclusion

If you can see properly rendered diagrams above (not just code blocks), then Mermaid integration is working correctly! The diagrams should:

Render as visual diagrams instead of code blocks
Adapt to the current theme (light/dark mode)
Be responsive and work on mobile devices
Handle errors gracefully if there are syntax issues

This enables us to create rich, visual documentation and blog posts with flowcharts, architecture diagrams, and process flows directly in Markdown.