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, 99 flashcards. 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.
AI-assisted diagram authoring	"add an SQS DLQ to the order pipeline diagram" → a reviewable text diff	• LLMs edit text DSLs reliably • editing a binary GUI file usually means regenerating the whole image with no diff
Text vs GUI trade-off	a marketing hero image in Figma vs. a sequence diagram in a PR	•Text wins for diagrams that travel with code (review, diffing, automation) •GUI tools win for one-off, precisely positioned, or non-engineer-authored pictures.
Source of truth vs. rendered image	`diagrams/context.puml` (source) + `diagrams/rendered/context.svg` (output)	• The text file is authoritative • a committed image is a build artifact regenerated by CI, never hand-edited
One diagram, one abstraction level	a Container-level diagram that starts showing internal class names	Mixing levels, such as a deployment topology combined with a call graph, confuses every audience it's meant to serve.

Table 2: Mermaid — Flowcharts

Flowcharts are Mermaid's most common diagram type and the easiest entry point: nodes are shapes, edges are arrows, and the whole thing reads like Markdown.

Syntax	Example	Description
flowchart declaration & direction	`flowchart LR` `A --> B`	Declares the diagram type and orientation: `TD`/`TB` (top-down), `LR` (left-right), `BT`, or `RL`.

The rest of this section is part of the full cheat sheet

Table 3: Mermaid — Sequence Diagrams

Sequence diagrams show how participants exchange messages over time, useful for documenting a single feature's call flow without touching architecture-level abstraction.

Syntax	Example	Description
sequenceDiagram & participants	`sequenceDiagram` `participant A` `participant B`	Declares the diagram and, optionally, the display order of participants ahead of their first message.

The rest of this section is part of the full cheat sheet

Table 4: Mermaid — Class & State Diagrams

Class diagrams model static object-oriented structure; state diagrams model how a system moves between a finite set of states. Both intentionally mirror PlantUML's syntax so diagrams can move between the two tools.

Syntax	Example	Description
Class definition & members	`class Animal{` `+String name` `+makeSound()` `}`	• Declares a class with attributes and methods grouped in one block • parentheses distinguish a method from an attribute

The rest of this section is part of the full cheat sheet

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.
AI-assisted diagram authoring	"add an SQS DLQ to the order pipeline diagram" → a reviewable text diff	• LLMs edit text DSLs reliably • editing a binary GUI file usually means regenerating the whole image with no diff
Text vs GUI trade-off	a marketing hero image in Figma vs. a sequence diagram in a PR	•Text wins for diagrams that travel with code (review, diffing, automation) •GUI tools win for one-off, precisely positioned, or non-engineer-authored pictures.
Source of truth vs. rendered image	`diagrams/context.puml` (source) + `diagrams/rendered/context.svg` (output)	• The text file is authoritative • a committed image is a build artifact regenerated by CI, never hand-edited
One diagram, one abstraction level	a Container-level diagram that starts showing internal class names	Mixing levels, such as a deployment topology combined with a call graph, confuses every audience it's meant to serve.

Table 2: Mermaid — Flowcharts

Flowcharts are Mermaid's most common diagram type and the easiest entry point: nodes are shapes, edges are arrows, and the whole thing reads like Markdown.

Syntax	Example	Description
flowchart declaration & direction	`flowchart LR` `A --> B`	Declares the diagram type and orientation: `TD`/`TB` (top-down), `LR` (left-right), `BT`, or `RL`.

Table 3: Mermaid — Sequence Diagrams

Sequence diagrams show how participants exchange messages over time, useful for documenting a single feature's call flow without touching architecture-level abstraction.

Syntax	Example	Description
sequenceDiagram & participants	`sequenceDiagram` `participant A` `participant B`	Declares the diagram and, optionally, the display order of participants ahead of their first message.

Table 4: Mermaid — Class & State Diagrams

Syntax	Example	Description
Class definition & members	`class Animal{` `+String name` `+makeSound()` `}`	• Declares a class with attributes and methods grouped in one block • parentheses distinguish a method from an attribute