Mermaid vs PlantUML Activity Diagrams: Syntax and Examples

This article focuses only on activity diagram expression. It does not cover Markdown support, documentation platform integration, plugins, or rendering services. For those broader tool differences, see the series overview: Mermaid vs PlantUML: Which diagram-as-code tool should you choose in 2026?.

The short version is simple: if you want to explain a business process, approval flow, or system workflow, Mermaid Flowchart is often enough. If you need a more formal UML Activity Diagram with start/stop semantics, structured branches, loops, forks, detach behavior, swimlanes, and exception paths, PlantUML is the stronger choice.

One important distinction: Mermaid primarily uses flowchart for this kind of process diagram. It can express many activity-diagram-like flows, but it is not a full UML Activity Diagram DSL. PlantUML has dedicated Activity Diagram syntax, so actions, branches, loops, parallel flows, termination, and swimlanes map more directly to UML activity semantics.

More precisely:

Mermaid is direct and lightweight. For product flows, user journeys, API handling steps, and lightweight technical documentation, flowchart TD and flowchart LR are easy to read and easy to embed in Markdown. If the goal is to show "how the steps move" rather than strict UML activity semantics, Mermaid is usually the simpler fit.

PlantUML has richer activity semantics. It supports dedicated start, stop, if/else/endif, while/endwhile, repeat/repeat while, fork/end fork, detach, and swimlane syntax. That makes it a better fit for long workflows, complex control structures, formal reviews, and architecture documentation.

This comparison is based on the official documentation:

• Mermaid Flowchart documentation
• PlantUML Activity Diagram documentation

Key Differences

In one sentence:

Mermaid is like using a flowchart to express activity; PlantUML is like writing a formal UML activity diagram as text.

Mermaid Can Express Common Activity Flows

Many business activity diagrams do not need strict UML semantics. They just need to show the workflow direction. Here is an order submission flow: receive the order, check stock, reserve items and charge payment if stock is available, or notify the customer if it is not.

Mermaid

flowchart TD
  Start([Start]) --> Receive[Receive order]
  Receive --> Check{Stock available?}

  Check -- Yes --> Reserve[Reserve items]
  Reserve --> Charge[Charge payment]
  Charge --> Confirm[Confirm order]
  Confirm --> Done((End))

  Check -- No --> Notify[Notify customer]
  Notify --> Done

PlantUML

@startuml
start
:Receive order;

if (Stock available?) then (yes)
  :Reserve items;
  :Charge payment;
  :Confirm order;
else (no)
  :Notify customer;
endif

stop
@enduml

For short workflows like this, Mermaid is easy to read and often closer to what non-UML readers expect from a process diagram. PlantUML's advantage is that the syntax itself expresses the activity control structure.

PlantUML Is Better for Loops and Parallel Work

When an activity diagram includes loops, parallel branches, or early termination, Mermaid can still draw the picture, but extra nodes, back edges, and labels carry much of the meaning. PlantUML can express those control structures directly.

Mermaid

flowchart TD
  Start([Start]) --> Validate[Validate order]
  Validate --> Risk{Risk detected?}

  Risk -- Yes --> Review[Manual review]
  Review --> Approved{Approved?}
  Approved -- No --> Reject[Reject order]
  Reject --> Done((End))
  Approved -- Yes --> ParallelStart[Continue fulfillment]

  Risk -- No --> ParallelStart
  ParallelStart --> Update[Update order status]
  ParallelStart --> Notify[Send notification]
  Update --> Join[Complete workflow]
  Notify --> Join
  Join --> Done

PlantUML

@startuml
start
:Validate order;

if (Risk detected?) then (yes)
  :Manual review;
  if (Approved?) then (yes)
  else (no)
    :Reject order;
    stop
  endif
endif

fork
  :Update order status;
fork again
  :Send notification;
end fork

:Complete workflow;
stop
@enduml

Mermaid can approximate the shape of this diagram, but the semantics are different:

• Mermaid expresses parallel work through multiple edges, while PlantUML has native fork semantics.
• Mermaid points to an end node for early termination, while PlantUML can use stop inside the branch.
• Mermaid loops are usually back edges, while PlantUML can use while or repeat.
• PlantUML code reads more like structured workflow logic, which helps when the diagram grows.

When to Choose Which

Choose Mermaid for activity-style diagrams when:

• You need to explain a product flow, approval process, or API workflow.
• The diagram is mainly nodes, decisions, and arrows.
• The diagram belongs in README, Markdown docs, or lightweight design notes.
• Readers care more about the flow than formal UML activity semantics.
• The diagram is not too long and does not need strict parallel, loop, or interrupt semantics.

Choose PlantUML when:

• You need formal UML Activity Diagram semantics.
• You need clear start, stop, loops, forks, and early exits.
• You want to structure a complex workflow with control blocks.
• You need swimlanes for roles, teams, systems, or services.
• You need stable style output for review or archival documents.

FAQ

Does Mermaid have a real UML Activity Diagram syntax?

Mermaid most commonly uses flowchart for activity-style workflows. It can draw many activity diagram scenarios, but it is not the same kind of dedicated UML Activity Diagram DSL that PlantUML provides.

Can Mermaid draw parallel activity?

Yes, approximately. You can connect one node to multiple following nodes and merge them later. If you need formal fork/join semantics, PlantUML is a better fit.

Is PlantUML always better for activity diagrams?

No. If the diagram is a short workflow explanation, Mermaid is lighter and easier to embed in documentation. PlantUML becomes more valuable when the flow needs formal semantics, swimlanes, loops, forks, or long-term maintenance.

How should I choose based only on diagram capability?

If the point is "show the steps," choose Mermaid. If the point is "model activity semantics and control structure," choose PlantUML.

Bottom line:

For activity diagrams, Mermaid is best for lightweight workflow explanation, while PlantUML is better for formal activity modeling. Both can draw the flow, but PlantUML expresses loops, parallel work, interrupts, and swimlanes more completely.

You can try the examples in the OnUML editor by switching between Mermaid and PlantUML modes.