How to Write Uml Diagram Markup in Plantuml

PlantUML lets you describe UML diagrams using plain text instead of drawing boxes and arrows by hand. If you've ever struggled with dragging shapes around in a diagram tool, or needed to keep diagrams in sync with code changes, writing UML markup in PlantUML solves both problems at once. You type a short text description, and PlantUML renders the diagram for you. The markup lives in your version control system alongside your code, so it's easy to update, review, and share.

This matters for developers, architects, and technical writers who need clear visual documentation without the overhead of graphical editors. Learning the markup syntax once gives you a repeatable skill you can use across every project.

What Is PlantUML and How Does the Markup Work?

PlantUML is an open-source tool that converts a plain-text description into UML diagrams. You write markup using a simple, domain-specific language (DSL) built around keywords like @startuml, class, actor, and -> for arrows. PlantUML then generates images in formats like PNG, SVG, or PDF.

The markup is not a programming language. There are no variables, loops, or complex logic (though it supports some basic preprocessing). You describe what should appear in the diagram, and PlantUML handles layout and rendering.

Here's a minimal example:

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

That's a valid sequence diagram with two participants and two messages. PlantUML figures out the spacing, the lifelines, and the arrow styles automatically.

What Diagram Types Can You Create?

PlantUML supports more than a dozen UML and non-UML diagram types. The most common ones developers use are:

Sequence diagrams show interactions between objects over time
Class diagrams show the structure of classes, attributes, methods, and relationships
Use case diagrams show actors and system functionality
Activity diagrams show workflows and decision logic
State diagrams show object states and transitions
Component diagrams show system components and dependencies
Deployment diagrams show infrastructure and deployment targets

You can also create non-standard diagrams like mind maps, JSON diagrams, and Gantt charts.

How Do You Write a Sequence Diagram in PlantUML?

Sequence diagrams are the most popular diagram type in PlantUML because the markup maps directly to how people think about interactions: who talks to whom, in what order.

The core syntax uses -> for solid arrows (synchronous messages) and --> for dashed arrows (return messages):

@startuml participant "Web Browser" as Browser participant "API Server" as API participant "Database" as DB Browser -> API: GET /users/42 API -> DB: SELECT FROM users WHERE id=42 DB --> API: user data API --> Browser: 200 OK (JSON) @enduml

Key syntax points:

Use participant to declare and optionally rename actors or systems
Use actor for human users in use case or sequence diagrams
Add notes with note right of or note left of
Group messages with alt, loop, opt, and par blocks

How Do You Write a Class Diagram?

Class diagrams use a slightly different syntax. You define classes with their attributes and methods inside curly braces:

@startuml class User { -id: int -name: String -email: String +getProfile(): Profile } class Profile { -bio: String -avatarUrl: String } User "1" --> "1" Profile : has @enduml

Relationships between classes use different arrow types:

-- for association (solid line)
--> for directed association
o-- for composition
-- for aggregation
..|> for interface implementation
--|> for inheritance

If you're working with microservices, this class diagram example for microservices architecture shows how to model service boundaries and shared contracts.

How Do You Write an Activity Diagram?

Activity diagrams describe workflows. PlantUML's activity diagram syntax uses a flowchart-like approach:

@startuml start :User submits login form; if (Valid credentials?) then (yes) :Generate JWT token; :Redirect to dashboard; else (no) :Show error message; :Increment failed attempt count; endif stop @enduml

You can add swimlanes by enclosing actions in |Department| blocks, and use fork/end fork for parallel activities.

For a comparison of how PlantUML activity diagram syntax stacks up against alternatives like Mermaid and Graphviz, see this markup language comparison.

Where Do You Write and Preview PlantUML Markup?

You have several options for writing and rendering PlantUML diagrams:

PlantUML online server paste your markup at plantuml.com/plantuml and get an instant image
VS Code extension the "PlantUML" extension by jebbs gives you live preview in the editor
IntelliJ IDEA plugin built-in PlantUML integration with preview pane
Command line render diagrams from .puml files using the PlantUML JAR
CI/CD pipelines auto-generate diagram images during builds so documentation stays current

For most people starting out, the online server or a VS Code extension with live preview is the fastest way to learn.

What Are Common Mistakes When Writing PlantUML Markup?

Several issues trip up beginners regularly:

Forgetting @startuml and @enduml tags. Every diagram needs these bookend markers. Without them, PlantUML won't parse the file.
Using the wrong arrow syntax. A single dash versus a double dash changes the line style. Mixing up -> and --> makes diagrams misleading.
Not escaping special characters. Characters like <, >, and " in labels can break rendering. Use escaped versions or backticks.
Overcomplicating a single diagram. If your sequence diagram has 30 participants, nobody will read it. Split large diagrams into smaller, focused ones.
Ignoring skinparam settings. The default font and color scheme may not match your documentation style. Use skinparam commands to adjust appearance.
Relying on auto-layout for complex class diagrams. PlantUML's layout engine is good but not perfect. Use hidden links and left to right direction to nudge the layout.

How Do You Organize Large Diagrams?

As projects grow, your PlantUML files can get long and hard to maintain. Here are practical ways to keep them manageable:

Use the !include directive to split shared components (like actor definitions or style files) into reusable files
Group related diagrams by feature or module one .puml file per diagram
Add title and header blocks so each diagram explains what it documents
Use !define and !definelong to create custom shortcuts for repeated patterns
Version-control your .puml files alongside source code so changes to diagrams show up in pull requests

What Tips Help You Write Better PlantUML Markup?

After working with PlantUML across many projects, these habits make the biggest difference:

Start with the simplest version first. Get the basic shape of the diagram working, then add detail. Debugging a 5-line diagram is much easier than a 50-line one.
Use meaningful aliases. Instead of relying on PlantUML to use the raw class or participant name, assign short, clear aliases with as.
Add comments. PlantUML supports single-line comments with ' (apostrophe). Use them to explain non-obvious markup choices.
Use themes. PlantUML has built-in themes you activate with !theme cerulean or similar. This saves you from manually styling every element.
Render as SVG for documentation sites. SVG output stays sharp at any zoom level and is better for web pages.
Learn from examples. The PlantUML FAQ page has dozens of syntax examples organized by diagram type.

How Do You Integrate PlantUML into Your Workflow?

Writing the markup is only part of the value. The real payoff comes when diagrams stay in sync with your codebase automatically.

Here's what that looks like in practice:

Store .puml files in your repository under a /docs/diagrams folder
Add a CI step that runs java -jar plantuml.jar docs/diagrams/.puml to generate images on every push
Reference the generated images in your README, wiki, or static site
Review diagram changes in pull requests just like you review code

This workflow eliminates the problem of outdated diagrams that no longer match the actual system.