Diagrams as Code (Mermaid, PlantUML, draw.io) Cheat Sheet

Updated 2026-07-31

Next Topic: Different Linters and Their Specifics Cheat Sheet

🧠Study flashcards on this topic99 cards · spaced repetition→

Diagrams as code means writing a flowchart, sequence diagram, or ER diagram as plain text and letting a renderer draw it, instead of dragging boxes around in a GUI and saving a binary image. It matters because a diagram written this way lives in the same repository as the thing it describes, gets reviewed as a normal pull-request diff, and can be regenerated the moment the system changes rather than quietly going stale in a wiki. The non-obvious part: the choice is not "text vs pictures" but "text vs GUI" — a text diagram still renders as a picture, it just has a diffable, AI-editable source behind it, which is why Mermaid (renders natively on GitHub, GitLab, and Notion) and PlantUML (the deepest diagram-type catalog) dominate engineering docs, while draw.io/diagrams.net and Excalidraw stay the right call for one-off, precisely-positioned, or non-engineer-authored pictures.

What This Cheat Sheet Covers

This topic spans 15 focused tables and 113 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.

Table 1: Foundations — What "Diagrams as Code" MeansTable 2: Mermaid — FlowchartsTable 3: Mermaid — Sequence DiagramsTable 4: Mermaid — Class & State DiagramsTable 5: Mermaid — Entity-Relationship DiagramsTable 6: Mermaid — Beyond the Core Diagram TypesTable 7: PlantUML — Core UML DiagramsTable 8: PlantUML — Non-UML & Specialized DiagramsTable 9: C4 Model & Architecture-as-CodeTable 10: draw.io / diagrams.net & ExcalidrawTable 11: Embedding Diagrams in Markdown & Docs SitesTable 12: Version Control, CI & Review WorkflowTable 13: Tooling — CLIs, Editors & RenderersTable 14: Alternative Diagram-as-Code LanguagesTable 15: Choosing the Right Tool & Common Pitfalls

Quick IndexSubscribe to unlock

A jump-to index of every table row in this cheat sheet.

Mind MapSubscribe to unlock

An interactive map of every table and concept in this topic.

Table 1: Foundations — What "Diagrams as Code" Means

Before touching any specific syntax, it helps to know why this approach exists and when it earns its keep versus a GUI tool. These are the ideas every other table in this sheet builds on.

Concept	Example	Description
Diagrams as code	`flowchart LR` `A[Client] --> B[API]` saved as `diagram.mmd`	Diagrams defined in plain text and rendered by a tool, instead of drawn and saved as a binary image.
Version-controlled diagrams	`git diff diagrams/context.puml`	Because the source is text, `git diff` shows exactly which node or relationship changed, the same as a code change.
Pull-request review of diagrams	a changed `.puml` file shows a line-level diff in the PR	Reviewers comment on the text diff line by line instead of approving a flattened image on trust.
Renderer ubiquity	a fenced ```mermaid block renders inline in a GitHub README	GitHub, GitLab, Notion, and most static-site generators now render Mermaid natively with zero setup.

Table 1: Foundations — What "Diagrams as Code" Means

Before touching any specific syntax, it helps to know why this approach exists and when it earns its keep versus a GUI tool. These are the ideas every other table in this sheet builds on.

Concept	Example	Description
Diagrams as code	`flowchart LR` `A[Client] --> B[API]` saved as `diagram.mmd`	Diagrams defined in plain text and rendered by a tool, instead of drawn and saved as a binary image.
Version-controlled diagrams	`git diff diagrams/context.puml`	Because the source is text, `git diff` shows exactly which node or relationship changed, the same as a code change.
Pull-request review of diagrams	a changed `.puml` file shows a line-level diff in the PR	Reviewers comment on the text diff line by line instead of approving a flattened image on trust.
Renderer ubiquity	a fenced ```mermaid block renders inline in a GitHub README	GitHub, GitLab, Notion, and most static-site generators now render Mermaid natively with zero setup.