PlantUML is especially useful when a diagram needs UML precision. Every source file begins with @startuml and ends with @enduml.
Document frame, aliases, comments, and includes
Every standard UML diagram has a start and end marker. Use aliases for long labels and move shared styling or libraries into includes.
@startuml
!theme plain
title Diagram Hub
' A single-line comment
/' A block comment '/
component "Render API" as API
component Store
API --> Store
@enduml- Use @startuml / @enduml for standard UML source; specialized diagrams use their own @start... / @end... wrappers.
- Aliases let labels contain spaces and punctuation.
- Use !include for shared styles or libraries, and !define / !if for preprocessing.
- title, caption, legend, header, footer, scale, hide/show, left to right direction, and skinparam apply document-level structure.
Sequence diagrams
Use named participants and arrows to describe an interaction over time.
@startuml
actor User
participant App
database Store
User -> App: Save
App -> Store: INSERT diagram
Store --> App: id
App --> User: Confirmed
@enduml- -> is a call; --> is a return or response.
- Use activate and deactivate to show an active execution.
- Group alternatives with alt / else / end.
Class diagrams
Model types, members, and the relationship between them.
@startuml
class Diagram {
+source: String
+render(): SVG
}
class Workspace {
+save()
}
Workspace "1" o-- "*" Diagram
@enduml- Use +, -, and # for public, private, and protected members.
- Relationship arrows include <|-- inheritance and o-- aggregation.
- Add multiplicity in quoted strings beside the relationship.
Activity and component views
Use activities for business flow and components for deployable or replaceable parts.
@startuml
start
:Validate source;
if (Valid?) then (yes)
:Render SVG;
else (no)
:Show error;
endif
stop
@enduml
@startuml
[Web app] --> [Render API]
[Render API] --> [Diagram store]
@enduml- Activity actions are written between colons and end with a semicolon.
- Use if / then / else / endif for a decision.
- Square brackets create quick component-style boxes.
Skinning and notes
Use a restrained skinparam block to match a product without obscuring UML semantics.
@startuml
skinparam backgroundColor transparent
skinparam roundcorner 14
skinparam ArrowColor #635BFF
component API
note right of API
Validates and renders
diagram source
end note
@enduml- skinparam controls global defaults.
- Notes can sit left, right, top, or bottom of an element.
- Keep custom skinning in a shared include when diagrams belong to one product.
Use case, object, component, and deployment
These declarations cover actor goals, object instances, logical components, and runtime infrastructure.
@startuml
actor User
usecase "Create diagram" as Create
User --> Create
object "draft:Diagram" as draft
component Web
node "iPhone" {
[PrivyMermaid]
}
Web --> [PrivyMermaid]
@enduml- Use case: actor, usecase, and relationships including -->, .>, and <|--.
- Object diagrams use object plus links and optional fields; package groups related elements.
- Deployment uses node, artifact, database, cloud, frame, and nested elements.
State, timing, and non-UML diagrams
PlantUML extends beyond core UML with state, timing, work-breakdown, mind-map, JSON, YAML, Gantt, and network-oriented diagrams.
@startuml
[*] --> Draft
Draft --> Published : submit
Published --> [*]
@enduml
@startmindmap
* Diagram Hub
** Guides
*** Mermaid
*** D2
@endmindmap- State diagrams use [*] for initial or final states and support composite states, notes, concurrency, forks, and choices.
- Timing diagrams model state/value changes over time with clocks, robust/concise elements, and highlights.
- Mindmap, WBS, JSON, YAML, Gantt, Salt UI mockups, regex, EBNF, and network diagrams each use a dedicated @start... / @end... wrapper.
Keep it useful
Three working rules
- Use PlantUML when UML notation carries meaning your audience expects.
- Keep a diagram focused on one question: structure, interaction, or process.
- Avoid mixing deeply detailed class and sequence information in one view.
Official sources
Further reading
Use the official references for version-specific details, niche syntax, and advanced renderer options.