PlantUML diagrams

PlantUML turns text into UML and architecture diagrams. Use a ```plantuml fenced block and mdbin renders it live, right in your document — or open the diagram tool to draw one on its own and download it as a PNG.

Every example below shows its source first, then what it renders to.

Adding a diagram#

Open a fence with plantuml, write PlantUML code between @startuml and @enduml, and close the fence:

```plantuml
@startuml
Alice -> Bob : Authentication request
Bob --> Alice : Authentication response
@enduml
```

Which renders as:

Click any diagram to open a larger, zoomable view.

The @startuml / @enduml pair is required. PlantUML works out which kind of diagram you mean from the statements inside — -> between participants makes a sequence diagram, class makes a class diagram, and so on — so the rest of this page is organised by kind.

Sequence diagrams#

The most common PlantUML diagram. Participants appear in the order you first mention them, and arrows carry messages.

```plantuml
@startuml
actor User
participant "Web app" as Web
database DB

User -> Web : submit form
Web -> DB : INSERT row
DB --> Web : id
Web --> User : 201 Created
@enduml
```

Solid arrows (->) are calls, dashed (-->) are returns. Add grouping, notes and activation bars for longer flows:

```plantuml
@startuml
Alice -> Bob : request
activate Bob

alt success
  Bob --> Alice : 200 OK
else failure
  Bob --> Alice : 500 Error
end

deactivate Bob

note right of Alice : Retries on 500
@enduml
```

Activity diagrams#

Flowcharts, in PlantUML's newer syntax. Activities are wrapped in : and ;.

```plantuml
@startuml
start
:Receive request;
if (Authenticated?) then (yes)
  :Load profile;
  :Render page;
else (no)
  :Redirect to login;
endif
stop
@enduml
```

Loops work the same way, with repeat / repeat while or while / endwhile.

Class diagrams#

```plantuml
@startuml
class Document {
  +String slug
  +String title
  +publish()
}

class Comment {
  +String body
  +int anchor
}

Document "1" *-- "many" Comment : has
@enduml
```

+ is public, - private, # protected. Relationship arrows carry the usual UML meanings: <|-- inheritance, *-- composition, o-- aggregation, --> association.

Component diagrams#

```plantuml
@startuml
package "Browser" {
  [Vue app]
}

package "Server" {
  [Laravel]
  [Redis]
}

[Vue app] --> [Laravel] : HTTP
[Laravel] --> [Redis] : queue
@enduml
```

State diagrams#

```plantuml
@startuml
[*] --> Draft
Draft --> Published : publish
Published --> Expired : ttl elapsed
Expired --> [*]
@enduml
```

Mindmaps#

```plantuml
@startmindmap
* mdbin
** Documents
*** Markdown
*** Diagrams
** Comments
** API
@endmindmap
```

Mindmaps use @startmindmap / @endmindmap rather than @startuml. The same goes for a few other kinds: @startjson, @startyaml, @startgantt, @startwbs and @startsalt all work.

JSON data#

```plantuml
@startjson
{
  "slug": "a1B2c3D4e5",
  "title": "Release notes",
  "comments": 3,
  "tags": ["release", "notes"]
}
@endjson
```

Theme aware#

Diagrams follow the page theme — toggle light/dark and they re-render to match. PlantUML's own !theme directive works too, as long as it names a theme bundled with the engine.

Limits and safety#

• Everything renders in your browser. There is no plantuml.jar, no Java, and no call to plantuml.com — the engine is compiled to WebAssembly and JavaScript and ships with the page. Nothing about your diagram leaves the reader's machine.
• Remote includes do not work. !include https://… and !includeurl are blocked: the renderer has no network access by design. A local !theme is fine.
• Sprite and icon libraries are not available. The emoji set, OpenIconic (<&cog>) and the bundled sprite libraries (AWS, material, tupadr3 and friends) are all left out: the engine fetches each of those over the network at render time, which the renderer has no access to. Use plain text labels instead.
• Diagrams larger than 4096 pixels on either axis are refused by the engine, which is what a "Diagram too large for browser rendering" message means. Split a sprawling diagram into several smaller ones.
• Up to 10 diagrams per document, each up to 10,000 characters of source. These caps keep a single document from hanging the reader's browser.
• Diagrams render lazily as they scroll into view, and one at a time, so a long document stays responsive.
• Class, component, state and deployment diagrams are laid out by Graphviz, which runs as WebAssembly. In a browser too old to allow that, those kinds show an error while sequence, activity, mindmap and JSON diagrams — which use PlantUML's own layout — still render.

Tips#

• Keep labels short. PlantUML lays diagrams out automatically, and shorter labels pack tighter.
• Name a participant once with as (participant "Web app" as Web) and use the short name afterwards.
• A diagram that won't render usually has a problem on the line the error block names — check that line before anything else.
• Prefer several small diagrams over one large one. They are easier to read, faster to render, and far less likely to hit the 4096-pixel ceiling.
• See the PlantUML documentation for the full syntax of every diagram kind.