PlantUML is a tool that allows you to create UML-diagrams based on text rather than in a visual editor. This has a few advantages like managing your diagrams in a VCS or copy-pasting blocks from one to another diagram. This post will show you how you can get started with PlantUML and some basic syntax to draw / write your first diagrams.

What you need

You need to install Java and Graphviz from here. Java is needed for all types of diagrams whereas Graphviz is not needed if you only do sequence and activity-diagrams. But I’d suggest to install both. After that you need the official PlantUML-Jar. You can either download it from their website or from here.

First steps

First of all you have to create a file that contains all your definitions. It can be any file with any extension. I like to use .puml to keep things organized. After creating a file, you can start writing diagrams. Each file has to start with a line containing just @startuml and has to end with a line containing @enduml. Between these two tags is where all definitions are written. To test the initial setup, paste the following into your file:

@startuml
Alice -> Bob: Foo
Bob -> Alice: Bar
@enduml

Now save the file and pass it to the previously installed JAR:

java -jar plantuml.jar myDiagram.puml

This will give you a PNG-file called myDiagram.puml.

Defining elements

In the previous example we defined the elements Alice and Bob on the fly. PlantUML sees that no seperate definition has been done for these 2 elements and creates them. Whenever you refer to either one later on in the diagram, it will map it to the first defined instance directly.

You can also define these elements explicitly. This can be useful if you want a special apperance for these elements or if you want to assign them a specific UML-element. These definitions can be anywhere in the file, but I like to keep them grouped together at the top of the file.

Styling your diagrams

You can give your diagrams custom styles to change color, shapes, sizes, etc. It looks a lot like CSS in web-development. All your style-definitions are written between style-tags. As an example, here is a style-definition that centers all texts within cards:

<style>
card {
	HorizontalAlignment center
}
</style>

Wrap-up

Now you should be able to easily create diagrams using PlantUML. They have a great PDF here explaining everything in more detail. I also have a follow-up post to this one explaining how you can utilize Gitlab and Gitlab’s CI/CD to manage your diagrams and convert them to pictures on the fly. Check it out here