Archgram.ioText-based diagramming has three popular languages: Mermaid, D2 and PlantUML. All three turn a few lines of text into a diagram you can keep in Git, and all three are good. The right choice depends less on features than on where the diagram will live and who has to read it. This guide gives a short way to decide.
The same system in three languages
Here is a tiny web service in Mermaid. The point is how little it takes: a few lines, and the picture is generated.
A web app, an API and a database in Mermaid
Mermaid: the one that renders everywhere
Mermaid's biggest strength is reach. GitHub and GitLab render Mermaid blocks inside Markdown files, and many documentation tools understand it too, so a diagram in a README or pull request shows up as a picture with no extra setup. It covers flowcharts, sequence, class, state and entity-relationship diagrams, Gantt charts and more. Its layout is automatic, which keeps files small but gives you limited control over placement.
Pick Mermaid when the diagram lives in Markdown, you want it to render without a build step, and a standard layout is fine.
D2: the one built for nesting
D2 is a newer declarative language designed for software architecture. Containers nest naturally (a service inside a cluster inside a region), connections can be labelled and styled, and you can choose between several layout engines, including ELK. It also has dedicated shapes for SQL tables and classes. It reads closer to a configuration file than to a drawing script, which many engineers like.
Pick D2 when your diagrams are deeply nested architecture views and you care how they look and lay out, and you can render them in your own pipeline or tool.
PlantUML: the one with the longest UML history
PlantUML has been around for many years and covers a very wide range of UML diagram types, with a large ecosystem of IDE plugins and libraries (including community C4 libraries). Rendering normally needs Java, and some diagram types need Graphviz, or a server that does it for you. That is easy in a build pipeline and less convenient in a browser.
Pick PlantUML when you need strict UML, you already have PlantUML tooling in your pipeline, or an existing documentation set is written in it.
A quick decision table
| If you mostly need… | Start with |
|---|---|
| Diagrams inside README files and pull requests | Mermaid |
| Nested architecture views with layout control | D2 |
| Formal UML across many diagram types | PlantUML |
| A hand-drawn, whiteboard feel | Excalidraw |
| Drag-and-drop editing of a finished picture | Draw.io |
You do not have to choose forever
The cost of picking the wrong language used to be a rewrite. Archgram edits Mermaid, D2, PlantUML, Draw.io and Excalidraw, and converts flow, sequence, class and entity-relationship diagrams between them. Before a conversion is applied, it shows what was simplified, because notations do not map one-to-one. So you can start in the language that renders where you need it, and move later. See Formats & Conversion for what converts and what does not.
Open the editor and try the same diagram in each language, or describe your system in a sentence and let the AI draft the first version.