Mermaid vs PlantUML: which to use for docs in Git

Use Mermaid when the diagram lives in Markdown on GitHub, GitLab or in Obsidian: it renders there without setup and runs in a browser. Use PlantUML when you need UML types Mermaid does not list, such as component, deployment, object or activity diagrams, and you can run Java or a PlantUML server. Both are free to use and both draw diagrams from text.

What follows is a side-by-side table, two code samples, and a short list of where each one wins. Facts about both tools come from their own documentation, checked on 2 November 2026, and links go to the source.

Mermaid vs PlantUML: what is different?

What does the same diagram look like in each?

The same two-message exchange. Mermaid names the diagram type on the first line. PlantUML wraps the diagram in start and end markers.

sequenceDiagram
  Alice->>Bob: Hello
  Bob-->>Alice: Hi

@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml

For a simple diagram the difference is small. It grows with the diagram: Mermaid has one syntax per type with a few shared ideas, and PlantUML has its own keywords, styling and include options for each of its types.

Where is Mermaid the better choice?

• It renders where your docs already are. GitHub, GitLab and Obsidian draw a mermaid block with no plugin and no server, so the Markdown file is the diagram.
• Nothing to install. It is JavaScript, so a browser draws it, and a live editor needs no account.
• A permissive license. MIT is simple to use in a product or a company wiki.
• Easy to edit by people who do not write code. Visual editors work on Mermaid; ours, for example, adds nodes with a plus button and writes the code for you.

Where is PlantUML the better choice?

• More UML types. Component, deployment, object, activity and timing diagrams are in PlantUML's list, and Mermaid's list has no diagram of those names. Mermaid has types PlantUML does not list, such as pie and git graph.
• Output from a server or a build. If a build already runs Java, PlantUML turns text files into PNG or SVG with no browser involved.
• An older, large ecosystem. It has been used for UML in documentation for a long time, so many teams already have PlantUML files.

How do I pick one?

• Docs in Markdown on GitHub, GitLab or Obsidian, mostly flowcharts, sequences, ER and Gantt: Mermaid.
• Formal UML with types Mermaid does not have, and a build or server that can run Java: PlantUML.
• Both in one repository: allowed, but readers on GitHub will see the PlantUML as code. Say in the file which tool draws it.
• Starting from nothing: try the same diagram in both for ten minutes. The syntax you can read a month later is the right one.

What does Folio do with each?

In Folio a Mermaid diagram is a block on the page, stored as an ordinary mermaid code block in the Markdown file, so the file renders on GitHub and GitLab as well. You can edit it on a canvas or as code. Mermaid diagrams in a team wiki shows three examples, and the Mermaid live editor is the same editor for free in your browser, with PNG and SVG export. For hand-drawn pictures Folio has boards built on Excalidraw.

What Folio does not do: it has no PlantUML renderer, so a PlantUML block is not drawn as a diagram, and the live editor does not read PlantUML. If your diagrams are PlantUML, render them to SVG or PNG outside Folio and add the image, or move them to Mermaid where the type exists.

Try it

Paste the Mermaid sample above into the live editor, then change it on the canvas. For a Gantt chart or an ER diagram, the same page has short examples with code. To keep diagrams next to the pages that explain them, read docs-as-code in the browser.

All posts