Mermaid Diagram Renderer

What Mermaid is and why it's everywhere now

Mermaid is a text-based syntax for diagrams: flowcharts, sequence diagrams, ER diagrams, Gantt charts, state machines, mind maps, and more. You write the diagram in a simple DSL; a renderer turns it into SVG. GitHub renders Mermaid in markdown files since 2022. GitLab, Notion, Obsidian, Slack canvases, and most modern documentation tools followed.

The killer feature: diagrams live in your repo as text. They diff, they're searchable, they don't go stale when someone leaves and takes the Lucidchart account with them. PRs can include diagram changes inline. The cost: the syntax is a bit clunky for complex diagrams; you'll occasionally fight the auto-layout. The benefit usually wins.

The diagram types most people use

• Flowchart — boxes and arrows. The most common type. flowchart TD (top-down) or LR (left-right). Node shapes: [] rectangle, () rounded, {} diamond, (()) circle.
• Sequence diagram — actors and messages over time. sequenceDiagram. Each line is an interaction: A->>B: text for solid arrow, A-->>B: text for dashed. Excellent for documenting API call patterns.
• State diagram — finite state machines. stateDiagram-v2. Transitions between named states. Perfect for documenting checkout flows, order lifecycles, auth state.
• ER diagram — entity relationships for databases. erDiagram. Cardinality notation: ||--o{ means "one to many", }o--o{ "many to many optional".
• Gantt chart — project schedules. gantt. Lighter weight than full project-management tools; great for sprint planning visualizations in a README.
• Class diagram — UML class structure. classDiagram. Used heavily in Java/C# documentation; useful but less common in dynamically-typed languages.
• Pie chart — simple stat visualizations. pie title X. Fine for low-stakes use; for real data viz use a charting library.

Common pitfalls

• Special characters in node labels. Parentheses, quotes, and pipes inside labels break the parser. Wrap the label in quotes: A["Some text with (parens)"].
• Layout doesn't match your mental model. Mermaid's auto-layout is opinionated. For flowcharts, TD vs LR radically changes the result. Sometimes you have to restructure your edges rather than fight the renderer.
• Long sequence diagrams scroll horizontally. Sequence diagrams expand horizontally with each participant. Past 6-7 participants they become hard to read. Split into multiple smaller diagrams.
• Subgraphs don't always nest cleanly. Flowcharts with nested subgraphs can render with crossed arrows that aren't reducible. Flat structure is usually clearer.
• Markdown rendering differences. GitHub, GitLab, Notion, and Obsidian don't all run the same Mermaid version. A diagram that works on GitHub may fail in Notion. Test where you'll actually publish.

Styling and themes

Mermaid supports a %%{init: {'theme': 'forest'}}%% directive at the top of any diagram. Available themes: default, neutral, dark, forest, base. For per-node styling, use style A fill:#f9f,stroke:#333,stroke-width:4px below the diagram body.

For complex theming, set the themeVariables object in the init block. The official theme docs at mermaid.js.org list every variable. For most cases, sticking with the default theme keeps your diagrams legible across light/dark modes without per-diagram tweaking.