PlantUML and Mermaid: Code Your Way to Professional Diagrams, Say Goodbye to Drag-and-Drop

Automatically generate sequence diagrams, class diagrams, state diagrams, and more. Escape the pain of manual layout and focus your time where it matters.

PlantUML offers rich syntax, perfect for complex, professional diagrams. Mermaid, on the other hand, is lightweight (no installation needed) and ideal for simpler diagrams within Markdown documents.

Installation and Configuration

PlantUML

1. Install dependencies.

   sudo apt install default-jre graphviz
   

2. Download the GPL version (full-featured) JAR package from the official download page.
3. Start a local server for VS Code to render diagrams in real-time.

   java -jar plantuml.jar -picoweb:8000:127.0.0.1
   

4. Install the jebbs.plantuml extension in VS Code. Afterward, set plantuml:Render to Local and plantuml:Server to http://127.0.0.1:8000/ in the settings.

Mermaid

Simply install the Markdown Preview Mermaid Support extension to enable real-time rendering in VS Code.

Sequence Diagrams

PlantUML

@startuml

title Sequence Diagram Demo

' typedef participants
participant Alice as A
participant Bob as B
participant Eve as E

' theme
skinparam monochrome true

' long time delay
... some long delay (NOT SUPPORTED IN MERMAID) ...

== step 1 (NOT SUPPORTED IN MERMAID) ==

A -> B: Authentication Request

' note
note over A, E
    **bold** ""monospaced"" --stroked--
    __underlined__ ~~waved~~ //italics//
    NOT SUPPORTED IN MERMAID
end note

' group
alt successful case
    B ->> A: Authentication Accepted
else Some kink of failure
    B ->x A: Response not reach
    group Custom lable
        loop 1000 times
            A -> B: retry
        end
    end
else Another type of failure
    B ->o A: Authentication Failure (NOT SUPPORTED IN MERMAID)
end

== step 2 ==

' auto num from 1, step 1
autonumber 1 1

[-> A: input
activate A
A->B: create request
activate B
B->E: DoWork
activate E
E-->B: WorkDone
destroy E
B-->A: request created
deactivate B

[<--A: output

 ' NOT SUPPORTED IN MERMAID
hide footbox
@enduml

Mermaid

• Does not support rich text formatting.
• Does not support step directives.
• autonumber cannot be reset, only globally effective.
• Does not support hide footbox.

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    title Sequence Diagram Demo

    participant A as Alice
    participant B as Bob
    participant E as Eve

    Note over A,E: this is note over
    Note left of E: this is note left

    A->>B: Authentication Request 1

    alt successful case
        B-->>A: Authentication Accepted
    else Some kink of failure
        B--xA: Response not reach
        loop 1000 times
            A->>B: retry
        end
    end

    autonumber
    A->>+B: create request
    B->>+E: DoWork
    E-->>-B: WorkDone
    B-->>-A: request created

    %% Notes are also simpler in Mermaid and do not support complex formatting like PlantUML's notes.
    %% '...' (long delay) and 'hide footbox' also don't have direct equivalents.

State Diagrams

PlantUML

@startuml
hide empty description

[*] --> State1
State1 --> [*]
State1 : this is a string
State1 : this is another string

State1 -> State2: <color:green> step1
State2 --> [*]

@enduml

Mermaid

stateDiagram
    direction LR

    [*] --> State1
    State1 --> [*]
    State1 : State1
    State1 : this is string

    State1 --> State2: step1
    State2 --> [*]

Flowcharts

PlantUML

@startuml
start

:Hello world;
:This is defined on
several **lines**;

if (am i right?) then (yes)
 :it's iotworker;
else (no)
endif

if (condition A) then (yes)
  :Text 1;
elseif (condition B) then (yes)
  :Text 2;
  stop
(no) elseif (condition C) then (yes)
  :Text 3;
(no) elseif (condition D) then (yes)
  :Text 4;
else (nothing)
  :Text else;
floating note right: elseif
endif


switch (test?)
case ( condition A )
  :Text 1;
case ( condition B ) 
  :Text 2;
case ( condition C )
  :Text 3;
case ( condition D )
  :Text 4;
case ( condition E )
  :Text 5;
floating note right: switch
endswitch

repeat :read data;
  :generate diagrams;
repeat while (more data?) is (yes)
floating note right: do while
->no;

while (data available?)
floating note right: while
  :read data;
endwhile

stop
@enduml

Mermaid

Compared to PlantUML, Mermaid has more limitations (e.g., the complex flowchart above looks less appealing):

• Floating notes: No equivalent syntax (floating note).
• Inline Markdown formatting: Node text does not support bold or other rendering.
• Automatic multiline text: Requires manual \n line breaks.
• Branch label position: Conditional labels (yes)/(no) must be written on the connecting lines.
• Native stop symbol: No built-in stop syntax; custom styles are needed.
• Repeat loop structure: No dedicated keywords; requires logical simulation.
• Chained elseif: Requires multiple nested decision nodes.
• Directional connectors: Syntax like ->no; requires explicit path definition.
• Smart layout: Complex logic may need auxiliary nodes.
• Syntax leniency: Stricter requirements for indentation and delimiters.

flowchart TD
    %% Start
    A(("start")) --> B["Hello world"]
    B --> C["This is defined on several lines"]
    
    %% First conditional (if/else)
    C --> D{am i right?}
    D -->|yes| E["it's iotworker"]
    D -->|no| F
    
    %% Complex if/elseif structure
    F --> G{condition A}
    G -->|yes| H["Text 1"]
    H --> S
    G -->|no| I{condition B?}
    I -->|yes| J["Text 2"]
    J --> Stop1["stop"]
    I -->|no| K{condition C?}
    K -->|yes| L["Text 3"]
    K -->|no| M{condition D?}
    M -->|yes| N["Text 4"]
    M -->|no| O["Text else"]
    L --> S
    N --> S
    O --> S
    
    %% Switch statement
    S[ ] --> P{test?}
    P -->|condition A| Q["Text 1"]
    P -->|condition B| R["Text 2"]
    P -->|condition C| T["Text 3"]
    P -->|condition D| U["Text 4"]
    P -->|condition E| V["Text 5"]
    Q --> W
    R --> W
    T --> W
    U --> W
    V --> W
    
    %% Do-While loop
    W[ ] --> X["read data"]
    X --> Y["generate diagrams"]
    Y --> Z{more data?}
    Z -->|yes| X
    Z -->|no| AA
    
    %% While loop
    AA[ ] --> AB{data available?}
    AB -->|yes| AC["read data"]
    AC --> AB
    AB -->|no| AD["stop"]
    
    %% Style definitions
    classDef stop fill:#000,color:#fff,stroke:#000
    class Stop1,AD stop;
    
    %% Notes (as comments)
    %% Complex if floating note: elseif
    %% Switch floating note: switch
    %% Do-While floating note: do while
    %% While floating note: while

Mind Maps

PlantUML

@startmindmap
* root node
	* some first level node
		* second level node
		* another second level node
	* another first level node
@endmindmap

Mermaid

mindmap
  root((root node))
    some first level node
        second level node
        another second level node
    another first level node

Class Diagrams

A class diagram is a UML (Unified Modeling Language) diagram used to display classes, interfaces, and their relationships within a system. Class diagrams are commonly used in software engineering, especially during object-oriented analysis and design, to visually describe the static structure of a system.

• Elements

• Relationships

PlantUML

• Elements

@startuml

class MyClass {
    -field1 : string
    #field2 : string
    +field3 : string
    -method1() : void
    #method2() : void
    +method3() : void
}

abstract class AbstractClass {
    +abstractMethod()
}

interface Interface {
    +interfaceMethod()
}

@enduml

• Relationships

@startuml

class Parent {
    +parentMethod()
}

class Child {
    +childMethod()
}

class Company {
    -employees Employee[]
    +addEmployee(Employee)
}

class Employee {
    -name String
    -position String
}

class House {
    -rooms Room[]
}

class Room {
    -size int
    -type String
}

class Teacher {
    -subject String
    +teach()
}

class Student {
    -grade int
    +study()
}

class Client {
    +request()
}

class Service {
    +process()
}

' Inheritance
Parent <|-- Child

' Aggregation
Company o-- Employee

' Composition
House *-- Room

' Association
Teacher -- Student

' Dependency
Client ..> Service

@enduml

Mermaid

• Elements

classDiagram
    class MyClass {
        -field1 : string
        #field2 : string
        +field3 : string
        -method1() : void
        #method3() : void
        +method2() : void
    }
    
    class AbstractClass {
        <<abstract>>
        +abstractMethod()
    }
    
    class Interface {
        <<interface>>
        +interfaceMethod()
    }

• Relationships

classDiagram
    %% Inheritance
    Parent <|-- Child
    
    %% Aggregation
    Company o-- Employee
    
    %% Composition
    House *-- Room
    
    %% Association
    Teacher -- Student
    
    %% Dependency
    Client ..> Service
    
    class Parent {
        +parentMethod()
    }
    
    class Child {
        +childMethod()
    }
    
    class Company {
        -employees Employee[]
        +addEmployee(Employee)
    }
    
    class Employee {
        -name String
        -position String
    }
    
    class House {
        -rooms Room[]
    }
    
    class Room {
        -size int
        -type String
    }
    
    class Teacher {
        -subject String
        +teach()
    }
    
    class Student {
        -grade int
        +study()
    }
    
    class Client {
        +request()
    }
    
    class Service {
        +process()
    }

• Relationship Descriptions

• Inheritance: <|-- indicates a child class inherits from a parent class.
• Aggregation: o-- represents a whole-part relationship where parts can exist independently.
• Composition: *-- represents a whole-part relationship where parts cannot exist independently.
• Association: -- indicates an association between classes.
• Dependency: ..> indicates one class depends on another.

• Visibility Modifiers

• + Public
• - Private
• # Protected
• ~ Package

Easter Egg: If you have more complex diagramming needs or simply prefer drag-and-drop, you might want to check out draw.io.