If you've ever needed to create a flowchart, sequence diagram, or system architecture sketch directly from text, you've probably run into three names: Mermaid, PlantUML, and D2. Each one lets you write diagrams as code no dragging boxes around in a GUI. But they differ a lot in syntax, capability, and the kind of workflow they fit into. Picking the wrong one can cost you hours of rewriting. This comparison breaks down the real differences so you can choose with confidence.

What exactly are Mermaid, PlantUML, and D2?

Mermaid, PlantUML, and D2 are all text-based diagram markup languages. Instead of using a visual editor, you write simple code that renders into diagrams. This approach keeps diagrams version-controlled, easy to update, and close to the documentation they describe.

Mermaid was created in 2014 and has become the most widely adopted of the three. GitHub supports it natively in Markdown files, and it's built into tools like Notion, Obsidian, and Confluence. It uses a simplified, Markdown-inspired syntax that feels familiar to anyone who writes documentation.

PlantUML is the oldest of the group, dating back to 2009. It runs on Java and uses a more verbose, keyword-driven syntax. It supports the widest range of diagram types, including UML-compliant diagrams, Gantt charts, mind maps, and even wireframes. If you need strict UML adherence, PlantUML is usually where people land.

D2 is the newest option, released in 2022 by Terrastruct. It was designed from scratch with modern developer workflows in mind. Its syntax reads almost like a configuration file, and it focuses heavily on layout quality and auto-arrangement. D2 produces some of the cleanest-looking diagrams with minimal manual positioning.

How do their syntaxes compare?

Syntax is where you'll feel the biggest day-to-day difference. Each language has a distinct style that affects how quickly you write and how readable your source files stay.

Mermaid syntax

Mermaid uses a lightweight, almost pseudocode-like approach. A simple flowchart looks like this:

graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Do something]
  B -->|No| D[Do something else]

It's fast to write and easy to scan. The downside is that when diagrams grow complex, the flat indentation model can get messy quickly.

PlantUML syntax

PlantUML uses a more structured, keyword-heavy format. The same flowchart would look something like:

@startuml
start
:Start;
if (Decision?) then (yes)
  :Do something;
else (no)
  :Do something else;
endif
stop
@enduml

It reads more like pseudocode with explicit start and end markers. This structure works well for complex logic but takes more characters to express simple relationships.

D2 syntax

D2 treats nodes and edges almost like nested objects:

start -> decision: ""
decision -> do_something: yes
decision -> do_something_else: no

The syntax is minimal and feels like writing a config file. Labels and connections are separated with colons and arrows, and you can add styling inline without cluttering the structure.

If you've worked with other diagram markup languages like Graphviz DOT, you'll notice that D2 borrows some of that object-graph thinking while keeping the syntax much shorter.

Which diagram types does each tool support?

This is where the tools diverge significantly. Not all diagram languages cover the same ground.

Mermaid supports: flowcharts, sequence diagrams, class diagrams, state diagrams, entity-relationship diagrams, Gantt charts, pie charts, requirement diagrams, and a few more. It covers the most common use cases well but doesn't go deep into niche diagram types.

PlantUML supports: everything Mermaid does plus activity diagrams, component diagrams, deployment diagrams, object diagrams, timing diagrams, network diagrams, wireframes, mind maps, regex diagrams, and many more. It has by far the broadest diagram type coverage.

D2 supports: flowcharts, sequence diagrams, class diagrams, entity-relationship diagrams, and a growing list. It's still adding new diagram types. As of its latest releases, it doesn't match PlantUML's breadth, but the types it does support tend to look better out of the box.

If your work involves software architecture diagrams specifically, all three handle the basics. PlantUML gives you the most options. D2 gives you the prettiest results. Mermaid gives you the easiest integration.

How well does each tool fit into documentation workflows?

A diagram tool that doesn't fit your workflow creates friction no matter how good its syntax is. Here's how each one handles real-world integration.

Mermaid wins here for most teams. GitHub renders it natively in Markdown files and pull requests. GitLab, Obsidian, Notion, Typora, VS Code, and many static site generators support it directly. You often don't need to install anything just write the code block and it renders.

PlantUML requires a server or local Java runtime to render. Many teams use the public PlantUML server or set up a private one. Confluence and IntelliJ have plugins. But the setup overhead is real, especially for teams that just want diagrams in their docs without extra infrastructure.

D2 has a CLI tool and a VS Code extension. It can output SVG, PNG, and PDF. There's no universal platform support like Mermaid's GitHub rendering, so you'll typically compile diagrams as part of a build process or CI pipeline. The D2 documentation site covers integration options well.

What about output quality and styling?

This matters more than people expect. A diagram that looks cluttered or ugly will get ignored in reviews and documentation.

D2 produces the cleanest output by default. Its auto-layout engine handles spacing, alignment, and label positioning well without manual tweaking. You can apply themes, custom fonts, and colors easily. The default style looks modern and professional.

PlantUML output varies. The default look is functional but dated think basic boxes and arrows with a hand-drawn skin option. You can customize heavily with skinparam commands, but it takes effort to make PlantUML diagrams look polished.

Mermaid output is clean and consistent, especially since it adopted its newer theming system. Five built-in themes (default, forest, dark, neutral, and base) give you quick style changes. The diagrams won't win design awards, but they're readable and professional enough for most documentation.

Which one is easiest to learn?

If you're new to diagram-as-code tools, here's a realistic learning timeline:

• Mermaid: You can write your first diagram in under 10 minutes. The syntax is forgiving, and since many platforms render it live, you get instant feedback. Best for beginners or teams that want adoption without training.
• D2: Takes a bit longer maybe 20-30 minutes because the syntax model is different from what most people expect. But once the click, diagrams come together fast. The documentation is good and examples are plentiful.
• PlantUML: The steepest curve. The syntax is more verbose, and understanding the full range of diagram types and customization options takes time. For developers already familiar with UML notation, some of it feels natural. For everyone else, expect a few hours before you feel comfortable.

Common mistakes when choosing between them

Picking based on popularity alone. Mermaid is the most popular, but popularity doesn't mean it's the best fit. If you need deployment diagrams or timing diagrams, Mermaid won't help, no matter how many people use it.

Ignoring your team's tools. If your team lives in GitHub and writes docs in Markdown, Mermaid's native support eliminates a huge barrier. If you use Confluence with existing PlantUML plugins, switching to something else just because it's newer adds unnecessary migration work.

Underestimating rendering dependencies. PlantUML needs Java or a server. D2 needs its CLI installed. Mermaid is often zero-install. Make sure your deployment pipeline and team machines can actually run whatever you pick.

Choosing based on one diagram type. Maybe D2 makes the prettiest flowcharts for your blog post. But does it handle the 12 diagram types your architecture docs need? Think about your full range of use cases before committing.

Quick reference: when to use which

1. Use Mermaid when you want diagrams directly in Markdown, need broad platform support, and your diagram needs are standard (flowcharts, sequence diagrams, ER diagrams, Gantt charts).
2. Use PlantUML when you need maximum diagram type coverage, strict UML compliance, or your team already has it set up in existing documentation infrastructure.
3. Use D2 when visual quality matters most, you want a modern syntax, and you're comfortable with a CLI-based workflow.

Our detailed comparison of these three tools covers additional edge cases and advanced features if you want to dig deeper.

Practical checklist before you decide

• ✅ List the diagram types your team actually uses not just the ones you might need someday
• ✅ Check which tools your documentation platform already supports natively
• ✅ Write the same diagram in all three tools and see which syntax feels right
• ✅ Test rendering in your team's environment (CI pipeline, wiki, IDE, GitHub)
• ✅ Ask your team one person's preference doesn't matter if five others struggle with it
• ✅ Try a real-world diagram, not a hello-world example, to stress-test layout quality
• ✅ Check how each tool handles diagram updates when requirements change this is where time adds up

Start by writing one actual diagram from your current project in each tool. That 30-minute test tells you more than any feature matrix ever will.