/plantuml-guide

Guide on using PlantUML

Creative Commons Zero v1.0 UniversalCC0-1.0

PlantUML Quick Guide

Installation and Running

Online

Local installation

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
    • 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

Visual Studio Code

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
  • 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