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:

Preparing diagram

Diagram Types

Flowcharts

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

Example:

Rendered Result:

Preparing diagram

Sequence Diagrams

Sequence diagrams show interactions between objects over time.

Example:

Rendered Result:

Preparing diagram

Class Diagrams

Class diagrams show the structure of classes and their relationships.

Example:

Rendered Result:

Preparing diagram

State Diagrams

State diagrams show the different states of a system.

Example:

Rendered Result:

Preparing diagram

Gantt Charts

Gantt charts show project timelines and schedules.

Example:

Rendered Result:

Preparing diagram

Pie Charts

Pie charts show proportional data.

Example:

Rendered Result:

Preparing diagram

Git Graphs

Git graphs show branch and commit history.

Example:

Rendered Result:

Preparing diagram

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:

Preparing diagram

Complete Examples

System Architecture Flowchart

Rendered Result:

Preparing diagram

Authentication Sequence

Rendered Result:

Preparing diagram

Theme Support

Each diagram is built twice at compile time:

• Light SVG — default Mermaid theme with your primary color (#FF5E19)
• Dark SVG — dark theme tuned to match the site

The docs page swaps SVGs when you toggle light/dark mode. Re-run npm run build:mermaid after changing theme config in scripts/mermaid/.

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 (test at Mermaid Live Editor)
• Run npm run build:mermaid after adding or editing a diagram
• If you see "Mermaid diagram not built", the build step did not produce an SVG for that chart hash

Theme Not Matching

• Light and dark SVG variants are generated at build time
• The site switches between them when you toggle theme
• Re-run npm run build:mermaid if you change Mermaid theme config in scripts/mermaid/

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