Diagrams as code: describe a diagram in text, render it as an image. No drag-and-drop, no binary file that diffs as noise, no diagram that goes stale because it’s a PNG nobody updates. The source lives in Git alongside the code it describes.

Mermaid

Mermaid is a JavaScript-based diagramming tool with a simple, readable syntax. It renders natively in GitHub Markdown, GitLab, and many documentation tools — paste a fenced code block with mermaid as the language and the diagram appears inline. No server needed for basic use.

Flowchart:

```mermaid
flowchart LR
    A[Source] --> B{Build}
    B -- pass --> C[Test]
    B -- fail --> D[Notify]
    C --> E[Deploy]
```

Sequence diagram:

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant DB
    Client->>API: POST /order
    API->>DB: INSERT order
    DB-->>API: ok
    API-->>Client: 201 Created
```

Other supported types: class diagrams, entity-relationship, state machines, Gantt charts, Git graphs.

The Mermaid live editor is the fastest way to iterate on a diagram.

PlantUML

PlantUML predates Mermaid and has a wider set of diagram types — UML sequence, class, component, deployment, activity, state, and non-UML types like C4 (architecture), BPMN, and Gantt. The syntax is more verbose than Mermaid but more expressive for complex diagrams.

PlantUML requires a rendering server (Java-based, self-hostable) or the hosted server at plantuml.com. Most IDE plugins (IntelliJ, VS Code) bundle a renderer.

Sequence diagram:

@startuml
actor Client
participant API
database DB

Client -> API : POST /order
API -> DB : INSERT order
DB --> API : ok
API --> Client : 201 Created
@enduml

Component diagram:

@startuml
package "Frontend" {
  [Web App]
}

package "Backend" {
  [API Server]
  [Worker]
}

database "PostgreSQL"

[Web App] --> [API Server]
[API Server] --> PostgreSQL
[Worker] --> PostgreSQL
@enduml

Which to use

Resources

• Mermaid documentation
• Mermaid live editor
• PlantUML documentation
• PlantUML online server