Mermaid vs PlantUML vs D2: Choose the Workflow First

The syntax is usually the cheapest part of choosing a diagram tool. The expensive part is discovering that nobody can render the file during review, or that every small edit rearranges the whole picture.

I would choose Mermaid, PlantUML, or D2 by workflow first, then test the layout with a diagram that resembles the real system.

My direct experience is strongest with Mermaid through Codelit's importer. The PlantUML and D2 comparisons below draw on their documentation, not a benchmark I ran across all three.

The best fit depends on the diagram's audience, notation, and publishing path. Favor the tool that lets the people maintaining the diagram review and regenerate it reliably, rather than the one with the most attractive isolated example.

The last row is where Codelit's interactive canvas sits. It is a different workflow, not evidence that text-based diagrams are inferior.

A text file stored with the code is valuable even if the service that first generated it disappears.

GitHub renders Mermaid in supported Markdown surfaces, while PlantUML and D2 require another rendering route. That difference can decide the choice for a README or pull request where reviewers should see the diagram without installing anything.

GitHub documents its supported diagram syntaxes and how to check the Mermaid version in use.

For the other formats, generate an image in CI or publish it through the docs build. A rendering service adds an availability dependency; an extension only helps readers who installed it.

Do not send private architecture source to a public rendering service without checking the data boundary. Diagram text can expose internal hosts, system names, and relationships.

Layout behavior depends on the selected engine and diagram type, not just the language. Test nesting, edge labels, fan-out, cycles, and long names before choosing a default. The same example can look very different after one more dependency is added.

PlantUML lists which diagram types use Graphviz. Sequence diagrams and several other types do not share that requirement.

D2 documents its engine choices and engine-specific features. Check licensing and deployment requirements for the engine you choose rather than assuming every D2 setup has the same capabilities.

I would not promise stable layout solely because an engine is deterministic. Renderer versions, font metrics, and input ordering can also change the result. Pin those inputs when repeatable output matters.

Use Mermaid's architecture syntax when its groups, services, junctions, and directional edges fit the diagram and the publishing renderer supports them. Do not choose it solely because the word "architecture" matches the document title.

The architecture syntax documentation describes the supported primitives and current syntax. A conventional flowchart may still be easier to render across hosts or maintain for a particular team.

Prototype the awkward case: nested groups, several crossing edges, and labels of realistic length. A clean three-box sample does not tell you much about a diagram containing the production system's exceptions.

Choose the output format based on validation and downstream use, not an assumed ranking of training-data volume. Without a controlled comparison, I cannot claim that one language is the most reliable across models or diagram types.

Codelit's early Mermaid work pushed me toward a typed graph representation. The model proposes nodes and edges; validation checks references and supported types; deterministic code emits the target syntax.

That pattern improves structural control. It does not prove that the model chose the correct services or dependencies. A fictional edge can be perfectly valid JSON and perfectly valid Mermaid.

A typed graph also supports other outputs, such as infrastructure scaffolding. That requires additional semantics; a drawing syntax alone is not a deployment specification.

Render at the stage that matches your publishing and performance constraints. Client-side rendering shifts work to the reader; build-time rendering shifts it to the documentation pipeline. Mermaid can also render ahead of time, so the language does not force one model.

Benchmark the route you will actually deploy. Record graph size, diagram type, engine, fonts, machine, and cold versus warm execution. An unlabeled render-time number is not a useful comparison.

Keep source close to the system it describes, make regeneration repeatable, and review the rendered result alongside the source diff. If committed images can drift from source, add a CI check that fails when regeneration changes the artifact.

Use explicit ownership for architectural claims. No diagram tool can detect every time the implementation stops matching its documentation.

Avoid choosing a project solely from its latest release date. Maintenance includes issue response, compatibility, security handling, and whether the existing feature set solves your problem. A release timestamp without that context is a weak signal.

I would start with Mermaid for GitHub-native documentation, evaluate PlantUML for UML-heavy work, and test D2 when architecture layout is the main constraint. I would choose one default and allow documented exceptions rather than forcing every diagram through the same notation.

The durable decision is the maintenance loop: who updates the source, who reviews its claims, and what checks the rendered result.

A modest diagram that stays accurate is worth more than a beautiful one the team cannot safely change.