PlantUML Quick Guide

• PlantUML Quick Guide
  • Installation and Running
    • Online
    • Local installation
    • PlantUML server
  • Diagram source code
    • Encoding
    • PNG metadata
  • Integrations
    • Visual Studio Code
      • Local render
      • PlantUMLServer render
    • IntelliJ IDEA
  • Resources

Installation and Running

Online

• Server-hosted
  • has ads
  • does not store diagrams in their servers
    • the whole diagram source code is compressed into the URL
    • the server decompresses the diagram's compressed text and generates the image with it
    • e.g., with diagram source code such as src/sequencediagram/simple.puml:
      • compressed into SoWkIImgAStDuNBCoKnELT2rKt3AJx9IA4ajBk5oICrB0Ke10000
      • view with the online server: https://www.plantuml.com/plantuml/uml/SoWkIImgAStDuNBCoKnELT2rKt3AJx9IA4ajBk5oICrB0Ke10000
• Client-side (pure JavaScript)
  • code: https://github.com/plantuml/plantuml-core

Local installation

• Requirements
  • Java
  • Graphviz
    • not needed if you only need sequence diagrams and activity diagrams
    • see https://plantuml.com/graphviz-dot
• Install
  • download and install the above requirements
  • download plantuml.jar
  • place plantuml.jar into a directory of your choice
    • no need to unpack
• Command line
  • see https://plantuml.com/command-line
  • java -jar plantuml.jar simple.puml
    • simple.puml is a text file with PlantUML commands, e.g., src/sequencediagram/simple.puml
    • outputs diagram to a file called simple.png, e.g., src/sequencediagram/simple.png
• GUI
  • java -jar plantuml.jar -gui or java -jar plantuml.jar -gui /source/directory
    • the diagram updates automatically if the diagram source code is modified

PlantUML server

• Options to run PlantUML locally or on a self-hosted server
• JEE server
  • download the plantuml.war file and copy it into the webapp directory of your server
• PlantUML PicoWeb server
  • start the embedded web server using java -jar plantuml.jar -picoweb:8080
  • only understands GET requests with the following patterns:
    • /plantuml/png/xyz....
    • /plantuml/svg/xyz....
  • to test: http://localhost:8080/
  • examples:
    • http://localhost:8080/plantuml/png/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000
    • http://localhost:8080/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000
  • GET requests are used by various PlantUML plugins
    • use plugins with the embedded server without the official online server
  • note: PicoWeb server is part of PlantUML code

Diagram source code

Encoding

• PlantUML defines a way to encode diagram source code
  • to facilitate communication of diagrams through URL, e.g., https://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000
• Diagram source code is encoded by:
  • encoding in UTF-8
  • compressing using the Deflate algorithm
  • re-encoding in ASCII using a transformation similar to Base64

$ cat path/to/simple.puml
@startuml
Alice -> Bob: test
@enduml

$ java -jar plantuml.jar -encodeurl path/to/simple.puml
Syp9J4vLqBLJSCfFib8eIIqk0G00

$ java -jar plantuml.jar -decodeurl Syp9J4vLqBLJSCfFib8eIIqk0G00
@startuml
@startuml
Alice -> Bob: test
@enduml
@enduml

PNG metadata

• Generated diagrams in PNG format include the diagrams' source code in the PNG metadata
  • can be disabled using the -nometadata option on the command line
• Extract diagram source code:
  • java -jar plantuml.jar -metadata path/to/simple.png

$ java -jar plantuml.jar -metadata path/to/simple.png
------------------------
path/to/simple.png

@startuml
Alice -> Bob: test
@enduml

PlantUML version 1.2023.4(Thu Mar 09 19:03:49 GMT 2023)
(MIT source distribution)
Java Runtime: OpenJDK Runtime Environment
JVM: OpenJDK 64-Bit Server VM
Default Encoding: UTF-8
Language: en
Country: GB

------------------------

$ exiftool -Plantuml path/to/simple.png
Plantuml                        : @startuml..Alice -> Bob: test..@enduml...PlantUML version 1.2023.4(Thu Mar 09 19:03:49 GMT 2023).(MIT source distribution).Java Runtime: OpenJDK Runtime Environment.JVM: OpenJDK 64-Bit Server VM.Default Encoding: UTF-8.Language: en.Country: GB.

Integrations

• This section describes some integrations that are available with PlantUML
• See https://plantuml.com/running for the full list

Visual Studio Code

• Extension: https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml
• Supports rendering using a locally installed plantuml.jar file (default) or with a PlantUML server installed locally or remotely
• See extension documentation for a complete list of settings

Local render

• Requirements
  • per Local installation
  • but not plantuml.jar
    • bundled with extension
    • unless you want to use your own copy
    • note: the bundled plantuml.jar can be pretty outdated!
• Settings
  • plantuml.jar: location of your own plantuml.jar

PlantUMLServer render

• Recommended for this extension
• Requirements
  • a PlantUML server
• Settings
  • plantuml.server: URL of your PlantUML server
  • plantuml.render: PlantUMLServer

IntelliJ IDEA

• Plugin: https://plugins.jetbrains.com/plugin/7017-plantuml-integration
• See plugin documentation
• Install the plugin through the IDE: IDE and Project Settings > Plugins...
• Notes
  • bundles plantuml.jar
  • support local and remote rendering
  • preview
    • rendered in SVG by default
    • updates quickly
    • clicking on text in diagram highlights text occurrences in source code
    • clicking on text in source code highlights in diagram (if enabled through settings)

Resources

• "Quick Start Guide." Plantuml.com, 2023, plantuml.com/starting. Accessed 29 Apr. 2023.
• "Frequently Asked Questions about installation." Plantuml.com, 2023, plantuml.com/faq-install. Accessed 29 Apr. 2023.
• "Call It from Your Script Using Command Line." Plantuml.com, 2023, plantuml.com/command-line. Accessed 29 Apr. 2023.
• "Text Encoding Format." Plantuml.com, 2023, plantuml.com/text-encoding. Accessed 29 Apr. 2023.
• "Standalone Tool Usage." Plantuml.com, 2023, plantuml.com/gui. Accessed 30 Apr. 2023.
• "The Servlet for Server Side." Plantuml.com, 2023, plantuml.com/server. Accessed 30 Apr. 2023.
• "Frequently Asked Questions." Plantuml.com, 2023, plantuml.com/faq. Accessed 30 Apr. 2023.
• "PlantUML - Visual Studio Marketplace." @Code, 2022, marketplace.visualstudio.com/items?itemName=jebbs.plantuml&ssr=false. Accessed 8 May 2023.