Dev Basics · 4 min read
Diagrams as Code with Mermaid
Mermaid turns a few lines of text into flowcharts, sequence diagrams, ER diagrams, and more. Because the source is plain text, diagrams live next to your code, show up in diffs, and never go stale in a forgotten drawing file.
Try it yourself with the related tool.
Write a Mermaid diagram →Advertisement
Why text beats drawing
Diagrams drawn in a visual tool are hard to update, so they drift out of date. A text diagram can be edited in seconds, reviewed in a pull request, and versioned with the code it describes. Layout is automatic, so you think about content, not pixel positions.
The diagram types you will use
flowchart LR draws boxes and arrows, such as A[Start] --> B{Valid?}. sequenceDiagram shows messages between participants over time — ideal for API and auth flows. erDiagram documents database tables and relationships. classDiagram, stateDiagram-v2, gantt, and pie cover most other needs.
Where it renders
GitHub, GitLab, Notion, Obsidian, and many documentation generators render Mermaid in fenced code blocks marked mermaid, with no plugins needed. Elsewhere, export the diagram to SVG or PNG.
Keeping diagrams readable
Mermaid lays everything out automatically, so huge diagrams get messy. Keep each diagram focused on one question, use subgraphs to group related nodes, and split a sprawling flowchart into several smaller ones.