Hi, this time I would like to share with my recent finding - PlantUml. I going to describe shortly how to use PlantUml on your blog posts or github wiki pages. I believe that in some particular cases, this tool, could be good alternative for draw.io.

PlantUml

PlantUml is an markup language designed to draw UML diagrams. Just look on example:


@startuml


package "Some Group" {
 HTTP - [First Component]
 [Another Component]
}

database "MySql" {
 
}


[Another Component] - HTTP
[Another Component] --> MySql


@enduml

Would be rendered as:

result

In case of simple class diagrams it could be also rendered as ascii text:


@startuml

title Classes - Class Diagram


class Dwelling {
 +Int Windows
 +void Lock()
}

class Apartment
class House
class Commune

Commune --> Apartment

@enduml

ascii:

,------------.                     
|Dwelling    |  ,-------.   ,-----.
|------------|  |Commune|   |House|
|+Int Windows|  |-------|   |-----|
|------------|  |-------|   |-----|
|+void Lock()|  `-------'   `-----'
`------------'       |             
                    |             
                    |             
              ,---------.         
              |Apartment|         
              |---------|         
              |---------|         
              `---------'         

Use with Markdown

If you like to insert your new shiny uml diagram have inserted into Markdown page, you have to options:

Render the image, upload to your graphic assets directory and simple link it:

![your uml](/assets/uml.png)

However above method would obviously work, but is not especially efficient. When you like to change anything in the diagram to make it updated, it would be necessary to render image and upload it again. Other option is to use planttext.com online editing tool instead, it gives you possibility to encode your uml into url like:

![result](https://www.planttext.com/plantuml/png/UhzxlqDnIM9HIMbk3XSNLq5YSdPYUgg2Kd1-Rgg2Ur5-QO6IGZMNWe97I4Y0Wgv2j5jcKN69WdD-Ra5-NcfUIInGAjenBxya8xK8MRIMIu4h9R4aCIcn66YORsLmOGx47A0C5nSM7K2pGLPWbzArKm0R0TJgagN0dGgG8010000)

Above method uses url encoding described as ‘special’, here it is why:

  1. First step is to encode plantUml sources into utf-8
  2. Compression with Deflate algorithm
  3. Encode back into plain ASCII with something like Base64

Have you noticed? “Something like…” what does it mean, they really used close to, look for yourself? - Unfortunately anything and nothing.

In result it’s impossible to use common online tools to achieve above encoding. You need to use PlantUml tool:

java -jar plantuml.jar -encodeurl yourdiagram

But don’t worry it’s planttext.com is working pretty stable for your small projects. If you like to setup it for your environment you can use Docker image to serve your own plant-uml server.

Use with Gists

With uml.mvnsearch.org service you can point to your gist identificator, and in response you would get an uml png.

![uml from gist](http://uml.mvnsearch.org/gist/7563171)

results with:

uml from gist

Place in GitHub Readme.md

In case of Github Readme.md files the best solution seams to be with use of planttext.com method or to use uml.mvnsearch.com service.

Interesting thing with mvnsearch is that it would make you able to point to your puml file directly from your markdown text.

![components](http://uml.mvnsearch.org/github/sratatata/space-invaders/blob/master/static/core-components.puml)

I like this method, because I can just edit my puml file and just forget it - It’s going to automatically keep my documentation up to date.

Summary

So If you are fun of using text based markup languages instead of buffy GUI tools, you can pretty fast write your uml definition and attach it to your markdown or asciidoc files, without huge investment.

Since now, you would probably find such uml diagrams made with plantUML on my blog more often.

Resources