Best Diagram as Code Tools
Diagram-as-code tools let you create architecture diagrams, flowcharts, and sequence diagrams using text-based specifications. This approach offers version control, reproducibility, and seamless integration with documentation workflows.
Why Diagram as Code
Traditional diagram tools (draw.io, LucidChart) produce binary files that are difficult to version control and review. Diagram-as-code tools:
* Store diagrams as plain text (diffable, reviewable in PRs).
* Integrate with Markdown documentation.
* Generate consistent output from the same source.
* Can be run in CI/CD pipelines.
* Work in any editor with syntax highlighting.
Mermaid
Mermaid is the most popular diagram-as-code tool, supported natively by GitHub, GitLab, and Notion. It renders diagrams from JavaScript-like syntax.
graph TD
A[Client] -->|HTTP| B[Load Balancer]
B --> C[Web Server 1]
B --> D[Web Server 2]
C --> E[(Database)]
D --> E
E --> F[Cache]
graph TD
A[Client] -->|HTTP| B[Load Balancer]
B --> C[Web Server 1]
B --> D[Web Server 2]
C --> E[(Database)]
D --> E
E --> F[Cache]
**Supported Diagram Types:**
* Flowchart, Sequence diagram, Class diagram
* State diagram, Entity Relationship diagram
* Gantt chart, Pie chart, Git graph
* User Journey, C4 diagram (decomposition)
sequenceDiagram
participant User
participant API
participant DB
User->>API: POST /login
API->>DB: SELECT user
DB-->>API: user data
API->>API: validate password
API-->>User: JWT token
**Pros**: Native GitHub/GitLab support, wide diagram type support, simple syntax, active development.
**Cons**: Complex diagrams can be slow to render, limited layout control, can look generic.
**Installation:**
npm install -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.png
PlantUML
PlantUML is a mature diagram-as-code tool with Java-based rendering and extensive diagram type support.
@startuml
actor User
participant "API Gateway" as GW
participant "Auth Service" as Auth
database "User DB" as DB
User -> GW: POST /auth/login
GW -> Auth: validate credentials
Auth -> DB: query user
DB --> Auth: user record
Auth --> GW: JWT token
GW --> User: 200 OK
@enduml
**Supported Diagram Types:**
* Sequence, Use Case, Class, Activity, Component
* State, Deployment, Object, Timing, Wireframe
* Archimate, Gantt, Mind Map, Work Breakdown
* Network diagram, JSON/YAML visualization
**Pros**: Most comprehensive diagram type support, mature and stable, powerful layout engine.
**Cons**: Java dependency, syntax can be verbose, slower rendering than Mermaid.
**Installation:**
# Using Docker
docker run -it --rm -v $(pwd):/data plantuml/plantuml diagram.puml
# Or using the plantuml CLI with Java
java -jar plantuml.jar diagram.puml
Excalidraw
Excalidraw is a whiteboard tool that produces hand-drawn style diagrams. It is not truly "diagram as code," but the .excalidraw format is JSON and can be version controlled.
**Pros**: Beautiful hand-drawn aesthetic, real-time collaboration, excellent for system design whiteboarding.
**Cons**: Not text-based, no code generation, manual placement.
Excalidraw has a CLI tool for embedding in workflows:
npx @excalidraw/cli export diagram.excalidraw --output diagram.png
Diagrams (Python)
Diagrams is a Python library for creating cloud system architecture diagrams. It includes icons for AWS, GCP, Azure, Kubernetes, and more.
from diagrams import Diagram, Cluster
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB
with Diagram("Web Service", show=False):
lb = ELB("Load Balancer")
web = EC2("Web Server")
db = RDS("Database")
lb >> web >> db
**Output Style:** Structured cloud architecture diagrams with official service icons.
**Pros**: Python-based, official AWS/GCP/Azure icons, programmatic control.
**Cons**: Limited to cloud architecture, not general-purpose diagramming.
**Installation:**
pip install diagrams
python diagram.py # Generates diagram.png
D2
D2 is a newer diagram-as-code language by Terrastruct, designed to address Mermaid's layout limitations.
Client -> Load Balancer: HTTP
Load Balancer -> Web Server 1
Load Balancer -> Web Server 2
Web Server 1 -> Database: SQL
Web Server 2 -> Database: SQL
Database -> Redis Cache: Cache read/write
**Pros**: Better auto-layout than Mermaid, cleaner output, fast rendering, animated diagrams.
**Cons**: Newer = smaller community, fewer integrations, limited diagram types.
Comparison Table
| Feature | Mermaid | PlantUML | Excalidraw | Diagrams | D2 |
|---------|---------|----------|------------|----------|-----|
| Language | JS-like | Java-like | JSON | Python | D2 DSL |
| Diagram types | 10+ | 20+ | Free-form | Cloud arch | 5+ |
| GitHub native | Yes | No | No | No | No |
| CI/CD support | CLI | CLI | CLI | Python | CLI |
| Layout quality | Good | Good | Manual | Algorithmic | Excellent |
| Speed | Fast | Medium | N/A | Fast | Fast |
| License | MIT | GPL | MIT | MIT | MPL |
Integration with Documentation
**Mermaid in Markdown:**
graph LR
A --> B
B --> C
Rendered automatically on GitHub, GitLab, and with Markdown renderers that support Mermaid.
**In MkDocs with Material Theme:**
# mkdocs.yml
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
**In VS Code:**
// Preview Mermaid in VS Code
"extensions": ["bierner.markdown-mermaid"]
Recommendations
* **For GitHub documentation**: Mermaid (native support, simplest syntax).
* **For complex UML**: PlantUML (most diagram types, best UML support).
* **For cloud architecture**: Diagrams (official icons, Python integration).
* **For whiteboarding**: Excalidraw (best visual output for brainstorming).
* **For polished output**: D2 (best auto-layout, modern tool).
Summary
Diagram-as-code tools have made technical diagrams maintainable and version-controllable. Mermaid is the most accessible choice with native GitHub support. PlantUML offers the widest diagram type coverage. D2 provides the best layout quality for modern tools. The key principle is to choose a tool that integrates with your existing documentation workflow -- if you already use Markdown in GitHub, Mermaid is the natural choice.