Writing documentation is a task that no one really likes especially when diagrams and flowcharts are involved. And then there’s the problem of which tools to use. One crafty tool is Draw.io with web and desktop editors but what to use if you want to write documentation as a code and see the changes clearly in text format and maintain source-controlled diagrams? Some of the tools for drawing diagrams with human readable text are mermaid and PlantUML.
mermaid
“Generation of diagrams and flowcharts from text in a similar manner as markdown.”
Mermaid is a simple markdown-like script language for generating charts from text via javascript. You can try it in live editor.
mermaid sequence diagram
You can write mermaid diagrams in text editor but it’s better to use some editor with plugins to preview your work. Markdown Preview Enhanced for Atom and VS Code can render mermaid and PlantUML. There are also dedicated preview plugins for VS Code and Atom.
To preview mermaid definition in VS Code with Markdown Preview Enhanced press Cmd-P to open Command palette and select Markdown Preview Enhanced: Open Preview
mermaid in VS Code with Markdown Preview Enhanced
To preview mermaid definition in VS Code with Mermaid Preview press Cmd-P to open Command palette and select Preview Mermaid Diagram
mermaid in VS Code with Mermaid preview
Generating PNG images from mermaid definitions
To use mermaid diagrams it’s useful to export them to PNGs. You can use the mermaid.cli tool which takes a mermaid definition file as input and generates a svg/png/pdf file as output.
Install mermaid.cli locally:
npm install mermaid.cli
Generate PNG:
./node_modules/.bin/mmdc -i input.mmd -o output.png
If you have plenty of defition files you can use the following script to generate PNGs:
#!/usr/bin/env bash
for mmd in ./docs/*.mmd
do
filename="${mmd##*/}"
echo "Generating $mmd"
./node_modules/.bin/mmdc -i $mmd -o ${filename%%.*}.png
done
Alternatively you can use node_modules/mermaid/bin/mermaid.js where mmd is the mermaid file.
PlantUML diagrams
PlantUML is used to draw UML diagrams, using a simple and human readable text description
PlantUML is used to draw UML diagrams, using a simple and human readable text description. Diagrams are defined using a simple and intuitive language (pdf) and images can be generated in PNG, in SVG or in LaTeX format.
You can use PlantUML to write e.g. sequence diagrams, use-case diagrams, class diagrams, component diagrams, state diagrams and deployment diagrams.
PlantUML example diagram
PlantUML diagram
A simple way to create and view PlantUML diagrams is to use Visual Studio Code and Markdown Preview Enhanced plugin which renders both PlantUML and mermaid diagrams. An alternative option is to use the plantuml plugin.
To preview a PlantUML diagram in VS Code with Markdown Preview Enhanced press Cmd-P to open Command palette and select Markdown Preview Enhanced: Open Preview
PlantUML in VS Code with Markdown Preview Enhanced
There’s an online demo server which you can use to view PlantUML diagrams. The whole diagram is compressed into the URL itself and diagram data is stored in PNG metadata, so you can fetch it even from a downloaded image. For example, this link opens the PlantUML Server with a simple Authentication activity diagram.
Running PlantUML server locally
Although you can render PlantUML diagrams online it’s better for usability and security reasons to install a local server. And this approach is important if you plan to generate diagrams with sensitive information. The easiest path is to run PlantUML Server Docker container and configure localhost as server.
docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
In VS Code config, open user setting, and configure like:
"plantuml.server": "http://localhost:8080",
"plantuml.render": "PlantUMLServer",
Now to preview diagram in VS Code press alt-D to start PlantUML preview.
PlantUML preview in VS Code and local server
You can also generate diagrams from the command line. First download PlantUML compiled Jar and run the following command which will look for @startXXX into file1, file2 and file3. For each diagram, a .png file will be created.
java -jar plantuml.jar file1 file2 file3
The plantuml.jar needs Graphviz for dot (graph description language) and on macOS you can install it from Homebrew: brew install graphviz
For processing a whole directory, you can use the following command which will search for @startXXX and @endXXX in .c, .h, .cpp, .txt, .pu, .tex, .html, .htm or .java files of the given directories:
java -jar plantuml.jar "directory1" "directory2"
Maintain source-controlled diagrams as a code
Documentation and drawing diagrams can be simple and maintaining source-controlled diagrams with tools like PlantUML and mermaid is achievable. These tools are not like the behemoth of Sparx Enterprise Architect but provide light and easy way to draw different diagrams for software development. You don’t have to draw lines and position labels manually as they are magically added where they fit and you even get as crude boxes and squares as thousands of dollars more expensive tools. Now the question is which tool to choose: PlantUML or mermaid?
This article was originally published on Rule of Tech, the author’s personal blog about technology and software development.
