PlantUML Code Blocks in Babel

Babel support for PlantUML

Introduction

PlantUML is a Java component for creating Unified Modeling Language (UML) diagrams and several non-UML diagrams with a simple language. Diagram images can be generated in PNG, SVG, and LaTeX formats.

PlantUML is integrated with a wide variety of software applications. Babel is a standard way to use PlantUML in Emacs.

Requirements and Setup

PlantUML blocks can be executed in one of two ways, requiring either

a working Java installation and access to the plantuml.jar component or
the plantuml executable available from your distribution's package manager

A working GraphViz installation is required for many diagrams.

Emacs has plantuml-mode, a major mode for editing PlantUML sources. There are detailed installation instructions, as well as instructions for integration with Org. While plantuml-mode does allow use of a remote server to render the diagram, please note that ob-plantuml does not currently support this functionality.

You will likely want to set the variables plantuml-jar-path and org-plantuml-jar-path with the path to your local installation of PlantUML. Alternatively, set the variable plantuml-default-exec-mode to executable to use your local plantuml executable.

Activate evaluation of PlantUML source code blocks by adding plantuml to org-babel-load-languages.

(org-babel-do-load-languages
 'org-babel-load-languages
 '((plantuml . t))) ; this line activates plantuml

Babel Features for PlantUML Code Blocks

Header Arguments

PlantUML code blocks default to :results file and :exports results.

If you wish to export the PlantUML code block to a file, you must specify a :file header argument. Alternatively, if you set :results to a value other than file, such as :results verbatim, then the ASCII PlantUML output will be inserted into the buffer below the code block.

PlantUML has these language-specific header arguments:

cmdline: specify command line arguments for PlantUML
java: arguments for the java runtimes (JRE)

Sessions

PlantUML does not support sessions.

Result Types

When the :file header argument has been specified, PlantUML code blocks return a link to the generated file. Alternatively, if :results is set to a value other than file, then the generated ASCII diagram will be inserted into the buffer.

Examples of Use

Here is the obligatory Hello World! example in PlantUML.

The PlantUML code block in the Org buffer:

#+begin_src plantuml :file images/hello-uml.png
Bob -> Alice : Hello World!
#+end_src

HTML output of the PlantUML code block:

Bob -> Alice : Hello World!

Here is an example using a theme.

The PlantUML code block in the Org buffer:

#+begin_src plantuml :file images/theme-uml.png
!theme spacelab
a -> b
b -> c
#+end_src

PNG output of the PlantUML code block:

!theme spacelab
a -> b
b -> c

Here is an example of ASCII output inserted directly into the buffer.

The PlantUML code block in the Org buffer:

#+begin_src plantuml :results verbatim
Bob -> Alice : Hello World!
#+end_src

ASCII output of the PlantUML code block:

,---.          ,-----.
|Bob|          |Alice|
`-+-'          `--+--'
  | Hello World!  |   
  |-------------->|   
,-+-.          ,--+--.
|Bob|          |Alice|
`---'          `-----'