PlantUML: The Complete Guide to Diagrams as Code

PlantUML is a text-based language for describing diagrams, most famously UML diagrams, that a renderer turns into a picture. Instead of dragging shapes on a canvas, you write a short block of text - participants, classes, states, and the relationships between them - and PlantUML lays it out for you. Because the diagram is text, it lives in your repository, versions in Git, and gets reviewed in pull requests like any other file, which is the whole appeal of the diagram-as-code approach.

This guide is a practical tour of PlantUML: how the syntax works, which diagram types it covers, how rendering happens, and how to weave it into a documentation workflow that survives contact with a changing codebase. PlantUML is a text format rather than a proprietary file, so you can reference an existing diagram and rebuild it visually in Atlas Diagram Studio at /diagrams when you want a polished, editable version. Atlas imports Mermaid natively, and the concepts here map closely onto that workflow, which the guide on diagram-as-code at /guides/diagram-as-code-guide develops further.

The core syntax every diagram shares

Every PlantUML diagram is wrapped in a start and end marker. For the classic UML types you open with @startuml and close with @enduml, and everything between those two lines is your diagram description. That framing tells the renderer where the diagram begins and ends, and it is the one piece of boilerplate you will type in every file. Some specialized diagrams use their own markers, like @startmindmap or @startgantt, but the @startuml pair covers the great majority of what people write.

Inside the markers, you declare elements and connect them with arrows. A basic sequence line looks like Alice -> Bob: Hello, which draws a solid arrow from Alice to Bob labelled Hello; a dashed reply uses Bob --> Alice: Hi back. The same arrow vocabulary - solid -> and dashed --> - recurs across diagram types with type-specific meaning. You can add a title with the title keyword, group elements, colour them, and add notes, but the essential loop is always the same: name things, then relate them with arrows.

The diagram types PlantUML supports

PlantUML's breadth is its strongest selling point. Where many text-diagram tools focus on one or two types, PlantUML aims to cover the full UML family plus a set of non-UML extras, so one tool and one syntax family handles most of what a software team needs to draw.

• Sequence diagrams: participants exchanging messages over time, using participant or actor and arrows like -> and -->.
• Class diagrams: classes with attributes and methods, connected by inheritance, association, and composition relationships.
• Use case diagrams: actors and use cases inside a system boundary, showing who does what.
• Activity diagrams: workflows and business processes with the newer start/stop and if/then syntax.
• Component diagrams: components and interfaces wired together to show system structure.
• State diagrams: an object's lifecycle, with states, transitions, and composite states.
• Extras beyond UML: mind maps, Gantt charts, JSON and YAML visualisation, and entity-relationship-style diagrams.

How PlantUML renders your text

PlantUML does not lay diagrams out by hand - it delegates the hard geometry to Graphviz for many diagram types, using the DOT layout engine to position nodes and route edges. This is why installing PlantUML sometimes asks you to install Graphviz too: the Java program parses your text into a structure, hands the layout problem to Graphviz, and composes the final image. Sequence diagrams are an exception, laid out by PlantUML's own engine, which is why they behave slightly differently from the graph-based types.

Because layout is automatic, you describe intent, not coordinates - a genuine strength, since a one-line change re-lays the whole diagram cleanly, but also a limitation, because you have less pixel-level control than a visual editor gives you. When you want that control, the pragmatic path is to draft the structure as PlantUML text, then reconstruct it in the editor at /diagrams for fine positioning, styling, and collaboration. The comparison at /guides/mermaid-vs-plantuml weighs PlantUML against Mermaid, the format Atlas imports directly.

Fitting PlantUML into a real workflow

The reason to adopt PlantUML is maintainability, and you only get that benefit if the diagrams live where the code lives. Keep your .puml files in the repository next to the modules they describe, so a change to the system and a change to its diagram happen in the same pull request and get reviewed together. This is the single habit that separates diagrams that stay accurate from diagrams that quietly rot, and it is the core message of the diagram-as-code guide at /guides/diagram-as-code-guide.

From there, decide how the rendered images reach your readers. Many teams render PlantUML in a documentation pipeline or an IDE plugin so the picture is always generated from the current text. For diagrams that need polish or non-technical collaboration, treat the PlantUML file as the source of truth for structure and rebuild the presentation version in Atlas Diagram Studio at /diagrams, where you get real-time editing and clean export. The type-specific tutorials that follow - sequence, class, use case, activity, component, and state - go deep on each diagram, and the broader guide at /guides/how-to-generate-diagrams-from-code covers generating this kind of text from source automatically.