PlantUML provides an extensive markup language to describe diagrams. The resulting diagrams can be exported to many formats, including graphics files such as .png, .svg and document formats such as .pdf and .html.
PlantUML can be used to define a UML diagram in text. As well as UML, several other diagram types are supported. For example, Gantt Charts visualisations of JSON data sets .
Including PlantUML Diagrams in Markdown
The CommonMark specification of Markdown does not include PlantUML within it’s scope. So PlantUML is an extension to the standard. This means that you are likely to have to install add-on extensions to your Markdown tools.
If your are using VSCode to edit and create Markdown documents, extension Markdown PDF is a great place to start. This extension converts Markdown files to .pdf and .html formats and supports embedded PlantUML, as well as Mermaid and LaTeX.
To add a diagram to a Markdown document, simply wrap the PlantUML code to begin with @startuml and end with @enduml, like this:
1@startuml
2 some PlantUML code here
3@enduml
PlantUML Diagrams: Going Beyond Markdown
You can use PlantUML to create complex diagrams as part of a larger documentation project.
Use VSCode to create and edit stand-alone, native PlantUML files (.wsd, .pu, .puml, .plantuml, .iuml).
VSCode extension PlantUML provides a live preview of PlantUML diagrams, short-cut Alt + D. The extension can also convert native PlantUML files (.wsd, .pu, .puml, .plantuml, .iuml) to a wide variety of formats (but not Markdown files with embedded PlantUML).
Themes
The look and style of diagrams is flexible. You have control over how diagrams are rendered. Each element in a diagram can have its own colour, specified in the PlantUML script. Also, an overall theme can be applied to a diagram.
Selecting a prebuilt theme or making your own.
There is a gallery of prebuilt themes.
Example: Class Diagram
Here’s a classic Class Diagram, illustrating inheritance. In this example, a theme called “crt-amber” has been used, resulting in a dark background with amber coloured lines and text. This is under your control, there are many themes to choose from or you can specify your own colours.
The above class diagram was generated by this PlantUML code:
1@startuml example_class_diagram
2
3' this is a comment line
4
5' set the theme
6!theme crt-amber
7
8' hide PlantUML "circle", to use classic UML Class notation
9hide circle
10
11' show class attributes visibility as -,+,#,~ rather than icons
12skinparam classAttributeIconSize 0
13
14
15' define class Pet and bold the name, using **
16class Pet as "**Pet**" {
17 -name: String
18 -weight: int
19 -canFly: boolean
20 +getName()
21 +setName()
22 +eat()
23}
24
25class Cat as "**Cat**" {
26 -scratches: boolean
27 +getScratches()
28 +setScratches()
29}
30
31class Dog as "**Dog**" {
32 -catChaser: boolean
33 +isCatChaser()
34}
35
36class Goldfish as "**Goldfish**" {
37 -color: String
38 +getColor()
39 +setColor()
40}
41
42' represent inheritance relationships
43Pet <|-- Cat
44Pet <|-- Dog
45' or like this
46class Goldfish extends Pet
47
48@enduml
Example: MindMap
Moving beyond UML diagrams, PlantUML supports a variety of other frequently used digram types. This is an example of a MindMap. Here a different theme has been used, this one is called “mimeeograph”, giving a light background with mauve coloured lines and text. A different theme could have been used, such as “crt-amber” as used above, or any theme frome those available .
Here’s the PlantUML that generated this mindmap:
1@startmindmap example_mindmap
2' set the theme
3!theme mimeograph
4
5* Summer Learning
6 ** Markdown
7 *** CommonMark
8 *** KaTeX
9 *** Mermaid
10 *** PlantUML
11 ** Hugo Framework
12 *** CI/CD
13 *** GitHub Tasks
14 *** Azure Static Sites
15
16left side
17
18** Rust
19** HTML5
20** CSS
21** JavaScript
22 *** Node
23 *** Electron
24** Angular
25** React
26
27@endmindmap
Example: Gantt Chart
This Gantt chart does not have a theme specified, so uses the default colours from PlantUML.
Here’s the PlantUML that generated this Gantt chart:
1@startuml example_gantt_chart
2' set the theme
3
4hide footbox
5saturday are closed
6sunday are closed
7project starts on 1 october 2021
8printscale daily zoom 2
9
10title New Idea Development
11
12[workshop ideas] as [task01] lasts 3 days
13[feasibility testing] as [task02] lasts 2 days
14[review for approval] as [task03] lasts 5 days
15[task01]->[task02]
16[task02]->[task03]
17-- finance --
18[estimate costs] as [task10] lasts 1 days
19[task01]->[task10]
20[task10]->[task03]
21-- mission, vision & values --
22[assess corporate compliance] as [task20] lasts 4 days and ends at [task03]'s start
23
24
25[approved] happens at [task03]'s end
26
27@enduml