Installing plantuml in ubuntu and jekyll integration

Sometimes one picture can say more than much of words. In many situations when we need to explain or understand something, we starts to draw some entities on paper and links them by arrows instinctly. After brainstorm meeting we often have artifacts like this:

Often people doesn't know how to store this kind of artifacts, how to track changes of this photo if picture on flipchart will be changed on next day. Someone will move photo to Microsoft Visio diagrams, which might take much time. Moreover, the problem of changes tracking with Visio-like software remains the same (binary format is very hard to compare). Also, reworking of Visio diagrams takes much time too.

TL;DR

Plantuml to the resque

I really love the plantuml tool for this task. It really very simple to use and produce an attractive images. The one of biggest reason to use plantuml is that all kind of diagrams are stored in text file. This allows to store diagrams in VCS and track all changes history by diffs.

For example, simple text like:

hide footbox
actor User
participant Service
database CredentialsStorage

User -> Service : login
Service -> CredentialsStorage : verify
Service <- CredentialsStorage : confirm
User <- Service : redirect to home page

will be rendered by plantuml to seuence diagram image:

Sequence diagrams are supported by plantuml out-of-the-box. Other kinds of diagrams supported with help of graphviz tools.

Plantuml is embeddable and have diagrams hosting support for many everyday-use tools like:

• Atlassian Confluence
• Doxygen
• Sphinx
• Jekyll

It is convenient though to create diagrams almost interactively with help of online editors. There are many:

• codeuml (automatic image generation),
• planttext (need to click refresh button)
• official plantuml web server (also need to click refresh button).

In this post I'll show how I made plantuml integration to my blog.

Jekyll integration

1. I've installed plantuml and graphviz with sudo apt-get install plantuml graphviz.

2. I've added gems: ['jekyll-plantuml'] entry to _config.yml.

3. I've installed jekyll-plantuml plugin with sudo gem install jekyll-plantuml.

4. Profit! Now I can draw any plantuml diagrams in Jekyll using this markup:

  {% plantuml %}
  From -> To : Action
  {% endplantuml %}

and have it rendered as image with jekyll build (actually, I use gulp to build my blog).

Update: The version of plantuml from sudo apt-get install plantuml package is not very fresh. You can't use latest added features gantt diagram with it.

You'd better to install plantuml manually instead, something like:

sudo mkdir /opt/plantuml
sudo wget http://sourceforge.net/projects/plantuml/files/plantuml.jar/download -O /opt/plantuml/plantuml.jar
sudo echo -e '#!/bin/bash\njava -jar /opt/plantuml/plantuml.jar "$1" "$2"' > /opt/plantuml/plantuml.sh
sudo chmod +x /opt/plantuml/plantuml.sh
sudo ln -s /opt/plantuml/plantuml.sh /usr/bin/plantuml

Happy drawing!