Mermaid Diagrams

Mermaid diagrams allow you to create beautiful, text-based diagrams directly in your MDX documentation. Flowcharts, sequence diagrams, class diagrams, and more - all with simple text syntax.

Overview

Mermaid is a diagramming and charting tool that uses text and code to generate diagrams. You can create complex diagrams using simple markdown-like syntax, and they'll automatically render with theme support.

Features

• ✅ Theme Support: Automatically matches your website's theme (light/dark)
• ✅ Text-Based: Write diagrams using simple text syntax
• ✅ Multiple Diagram Types: Flowcharts, sequence diagrams, class diagrams, Gantt charts, and more
• ✅ Responsive: Adapts to different screen sizes
• ✅ No External Tools: Create diagrams directly in your MDX files
• ✅ Styled Container: Beautiful bordered container matching your theme

Basic Usage

Simply use a mermaid code block in your MDX:

Rendered Result:

Diagram Types

Flowcharts

Flowcharts are perfect for showing processes, workflows, and decision trees.

Example:

Rendered Result:

Sequence Diagrams

Sequence diagrams show interactions between objects over time.

Example:

Rendered Result:

Class Diagrams

Class diagrams show the structure of classes and their relationships.

Example:

Rendered Result:

State Diagrams

State diagrams show the different states of a system.

Example:

Rendered Result:

Gantt Charts

Gantt charts show project timelines and schedules.

Example:

Rendered Result:

Pie Charts

Pie charts show proportional data.

Example:

Rendered Result:

Git Graphs

Git graphs show branch and commit history.

Example:

Rendered Result:

Syntax Reference

Flowchart Shapes

• [Rectangle] - Rectangle node
• (Round edges) - Rounded rectangle
• ([Stadium]) - Stadium shape
• [[Subroutine]] - Subroutine
• [(Database)] - Cylinder/Database
• ((Circle)) - Circle
• {Diamond} - Diamond/Decision
• {{Hexagon}} - Hexagon
• [/Parallelogram/] - Parallelogram
• [\Trapezoid\] - Trapezoid
• [/Trapezoid Alt\] - Trapezoid (alt)
• [>Flag] - Flag

Arrows

• --> - Solid arrow
• -.-> - Dotted arrow
• ==> - Thick arrow
• -- - Solid line
• -.- - Dotted line
• == - Thick line

Styling

You can style nodes with classes:

Rendered Result:

Complete Examples

System Architecture Flowchart

Rendered Result:

Authentication Sequence

Rendered Result:

Theme Support

Mermaid diagrams automatically adapt to your website's theme:

• Light Mode: Uses default Mermaid theme with light backgrounds
• Dark Mode: Uses dark Mermaid theme with dark backgrounds
• Primary Color: Uses your theme's primary color (#FF5E19) for highlights

The theme switches automatically when you toggle between light and dark modes.

Best Practices

1. Keep diagrams simple: Complex diagrams can be hard to read
2. Use descriptive labels: Make node and edge labels clear and meaningful
3. Organize with subgraphs: Use subgraphs to group related elements
4. Add titles: Use titles to provide context
5. Test both themes: Ensure diagrams look good in both light and dark modes
6. Use appropriate diagram types: Choose the right diagram type for your use case

Common Patterns

Decision Tree

Process Flow

Component Relationships

Troubleshooting

Diagram Not Rendering

• Check that the mermaid code block syntax is correct
• Ensure the diagram syntax is valid Mermaid syntax
• Check browser console for errors
• Verify that mdx-mermaid is properly configured

Theme Not Matching

• The diagram theme automatically matches your website theme
• If it doesn't match, check that next-themes is properly configured
• The diagram uses the same theme as the rest of your site

Diagram Too Large

• Use subgraphs to organize large diagrams
• Break complex diagrams into multiple smaller diagrams
• Consider using different diagram types for different aspects

Resources

• Mermaid Documentation - Complete Mermaid syntax reference
• Mermaid Live Editor - Test your diagrams online
• Mermaid Examples - Tutorials and examples

Next Steps

• Excalidraw Diagrams - Learn about interactive Excalidraw diagrams
• Tabbed Content - Learn about multi-tab sections
• Code Blocks - Learn about syntax highlighting