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.