Diagram Markup Language Syntax Comparison Guide

If you've ever tried to switch from one diagram-as-code tool to another, you already know the frustration. The syntax that worked perfectly in PlantUML throws errors in Mermaid. The flowchart you wrote in D2 looks nothing like what you expected when you paste it into Graphviz. Comparing diagram markup language syntax isn't just an academic exercise it directly affects how fast you can document systems, onboard teammates, and maintain diagrams alongside your codebase. This article breaks down the real differences between the most popular diagram markup languages, with practical examples you can use right now.

What does diagram markup language syntax actually mean?

A diagram markup language is a text-based format that lets you describe diagrams using code instead of dragging shapes around in a visual editor. The syntax is the specific set of keywords, symbols, and rules each language uses to define elements like nodes, edges, containers, and styles.

Think of it like programming languages. Python and JavaScript both let you build web apps, but they use completely different syntax to do it. Similarly, PlantUML, Mermaid, Graphviz/DOT, D2, and Structurizr DSL all let you create diagrams, but each has its own way of expressing the same visual ideas.

When people search for diagram markup language syntax comparison, they usually want to understand how the same diagram would look written in multiple languages so they can pick the right one or migrate between them.

Why would you need to compare syntax across diagram markup languages?

There are several real reasons developers and technical writers compare these tools:

Team adoption. Your team uses PlantUML, but a new hire prefers Mermaid because it renders natively in GitHub and GitLab markdown. You need to understand both to make a fair decision.
Platform limitations. Some tools work better in specific environments. Mermaid is embedded in Notion, Obsidian, and many wikis. PlantUML requires a server or local rendering setup. Graphviz is common in academic and data science contexts.
Diagram complexity. A simple sequence diagram might look similar across tools, but once you need nested components, styling, or large architectures, the syntax differences become significant.
Migration. You have hundreds of PlantUML files and your organization wants to move to a different tool. You need to know what translates directly and what requires manual rework.

For teams working on machine learning pipelines, the choice of diagram language can affect how clearly you communicate complex data flows to both engineers and stakeholders.

How do PlantUML and Mermaid syntax compare for common diagrams?

These are the two most popular diagram markup languages, so let's start here with concrete examples.

Flowchart syntax

PlantUML:

@startuml start :User submits form; if (Valid input?) then (yes) :Save to database; else (no) :Show error message; endif stop @enduml

Mermaid:

flowchart TD A[User submits form] --> B{Valid input?} B -->|yes| C[Save to database] B -->|no| D[Show error message]

PlantUML uses a more imperative, step-by-step style for flowcharts. Mermaid uses a declarative approach where you define nodes and connections separately. Neither is objectively better PlantUML reads more like pseudocode, while Mermaid reads more like a graph definition.

Sequence diagram syntax

PlantUML:

@startuml Client -> Server: GET /api/users Server -> Database: SELECT FROM users Database --> Server: Result set Server --> Client: 200 OK (JSON) @enduml

Mermaid:

sequenceDiagram Client->>Server: GET /api/users Server->>Database: SELECT FROM users Database-->>Server: Result set Server-->>Client: 200 OK (JSON)

Sequence diagrams are where the two languages look most similar. The main syntax difference is that Mermaid uses >> for solid arrows and >> with a dash prefix for return arrows, while PlantUML uses -> and -->.

Class diagram syntax

PlantUML:

@startuml class User { +String name +String email +login(): void } User "1" --> "" Order : places @enduml

Mermaid:

classDiagram class User { +String name +String email +login() void } User "1" --> "" Order : places

Class diagrams are nearly identical between the two. The key difference is that PlantUML uses a colon before the return type in methods, while Mermaid places the return type after the method name with no colon.

How does Graphviz (DOT) syntax differ from both?

Graphviz uses a fundamentally different model. It's a graph description language, not a diagram markup language. You describe nodes and edges in a graph structure, and the layout engine decides where to place everything.

Graphviz (DOT) example:

digraph G { rankdir=TB; A [label="User submits form"]; B [label="Valid input?", shape=diamond]; C [label="Save to database"]; D [label="Show error message"]; A -> B; B -> C [label="yes"]; B -> D [label="no"]; }

Graphviz gives you more control over layout algorithms (rankdir, subgraphs, clustering) but requires more verbose syntax. There's no built-in concept of sequence diagrams or activity diagrams it's purely about nodes and edges. This makes it powerful for custom graph visualizations but less convenient for standard software diagrams.

A detailed DOT language reference is available on the official Graphviz documentation site.

Where does D2 fit into the comparison?

D2 is a newer diagram scripting language that aims to be more readable and require less boilerplate than its predecessors.

D2 example for a similar flowchart:

submit: User submits form { shape: rectangle } validate: Valid input? { shape: diamond } save: Save to database { shape: rectangle } error: Show error message { shape: rectangle } submit -> validate validate -> save: yes validate -> error: no

D2 uses a more JSON-like structure with curly braces and doesn't require you to predefine diagram types (no flowchart or sequenceDiagram declaration). It also has built-in support for themes, icons, and connection labels with less syntax. The trade-off is that it has a smaller ecosystem and fewer integrations compared to PlantUML or Mermaid.

What are the most common mistakes when comparing or switching diagram markup languages?

Assuming direct syntax translation. A PlantUML activity diagram won't copy-paste into Mermaid without changes. Even where syntax looks similar (like sequence diagrams), arrow notation and keyword spacing differ.
Ignoring rendering differences. The same conceptual diagram can look very different when rendered. PlantUML tends to use more compact layouts; Mermaid often produces wider diagrams. Test both outputs, not just the code.
Forgetting about ecosystem support. Check whether your target tool works in your environment. If you're using web-based diagram code editors, Mermaid has broader support. If you need enterprise features like C4 model diagrams, PlantUML has more mature support through its C4 standard library.
Overlooking extensibility. PlantUML supports custom sprites, includes, and macros. Mermaid has a more limited extension mechanism. If your team uses advanced features, switching may mean losing functionality.
Not testing with real diagrams. A syntax comparison table can't show you how a 50-node architecture diagram actually renders. Always test with your real use cases before committing to a switch.

Which diagram markup language should you actually choose?

There's no universal answer, but here's a practical framework based on common situations:

Choose Mermaid if your team lives in GitHub, GitLab, Notion, or Obsidian. Native rendering in markdown files is a major advantage with zero setup.
Choose PlantUML if you need advanced diagram types (timing diagrams, Gantt charts, C4 architecture models) or want powerful macros and includes for managing large diagram sets.
Choose Graphviz if you're working on academic papers, custom graph visualizations, or need fine-grained control over layout.
Choose D2 if you want modern, readable syntax with built-in theming and don't mind a newer, smaller ecosystem.
Choose Structurizr DSL specifically for C4 model software architecture documentation with workspace-level model management.

If you're diagramming complex systems like microservices architectures, PlantUML's syntax supports detailed component and deployment diagrams that map well to real infrastructure.

Quick syntax reference: the same idea in five languages

To make comparison concrete, here's how you express "A calls B, B returns result to A" in each language:

PlantUML: A -> B : request / B --> A : result
Mermaid: A->>B: request / B-->>A: result
Graphviz: A -> B [label="request"] / B -> A [label="result", style=dashed]
D2: A -> B: request / B -> A: result {style.stroke-dash: 3}
Structurizr: Relationships are defined at the model level: A -> B "request"

The core concept is the same everywhere. The differences are in how you express arrow direction, labels, styling, and return/dashed lines.

Practical checklist for comparing diagram markup languages

Before you commit to a diagram markup language for your team or project, work through this list:

Write your three most common diagram types (flowchart, sequence, architecture) in two or three candidate languages.
Render each one and compare the visual output not just whether the code works, but whether the result is readable.
Check integration with your existing tools (CI/CD pipelines, wikis, editors, version control).
Test with a real, complex diagram from your project not a toy example.
Verify the rendering performance with large diagrams. Some engines slow down noticeably past 30-40 nodes.
Ask your team which syntax they find easier to read and write. Developer experience matters for adoption.
Document your choice and create a small template library so teammates can start using the language immediately without hunting for syntax references.

Start with one real diagram. Pick the language that lets you express it most clearly with the least friction. That's the right choice for your context.