Generating documentation as code with mermaid and PlantUML

Writing documentation is always a task which isn't much liked and especially with diagrams and flowcharts there's the problem of which tools to use. One crafty tool is 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? One of the tools for drawing diagrams with human readable text are mermaid and PlantUML.


"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's 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
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 mermaid.cli tool which takes a mermaid definition file as input and generates 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
    echo "Generating $mmd"
    ./node_modules/.bin/mmdc -i $mmd -o ${filename%%.*}.png

Alternatively you can use node_modules/mermaid/bin/mermaid.js $mmd 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, usecase diagrams, class diagrams, component diagrams, state diagrams and deployment diagrams.

PlantUML example diagram:

PlantUML diagram

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. Alternative option is to use plantuml plugin.

To preview 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?

10 thoughts on “Generating documentation as code with mermaid and PlantUML”

  1. PlantUML can also be run locally on macOS just as a jar file. I do that regularly as it's integrated into Doxygen - I have all my design docs in Markdown with simple embedded diagrams. Then the text is checked in alongside code and easily diffed.

    To create the diagrams initially I use which is hosted PlantUML.

  2. GitLab support both Mermaid and Plantuml into it's markdown.
    Since my organization uses GitLab, it is isteresting to write files that embed UML explaining the project.
    I would like to know if GitHub suppport this...

  3. Just finished two day evaluation of both.

    Plant UML is definitely more mature (older) and solves very wide number of UML issues and different kinds of diagrams. It is not implemented in a "modern way" using javascript, but java. That might be the actuall advantage to some folks. Basically it is java server returning images generated from PlantUML language. It is complex to run localy for individuals or smaller teams. Especialy on Windows machines. Even using VS Code. Using public www based server(s) is of course possible, buit not an option for many teams.

    Mermaid is just a pretty small, wildy popular, JS library, made by one man team with 47 contributors ... There is no server required. Images are produced dynamically by JS code behind. There is also a CLI tool.

    Good example of Mermaid nifty integration into the markup is HUGO (static sites generator) Learn Theme. In scope Mermaid is much smaller. For "documentation with diagrams" kind-of-a jobs, I think that is enough.


    If one wants/needs humongous UML diagrams one would be much better off with VISIO or SPARX or some such behemoth , for a ridiculous price naturally. (semi) free is also well rounded and mature but missing few UML features, that PlantUML does provide (generics, etc.). ArchiMate is an free option but is way too much TOGAF oriented, which makes it complex.

    In any case drawing large and complex diagrams by typing them becomes much slower than actually drawing them. Keep that in mind.

    But if you still think you can do this, by no means use PlantUML. Most likely using VS Code plugn.

    I will have to deliver architecture documentation on the next project, not code. I think, I am going to package that as HUGO produced static site that also uses Mermaid diagrams.

  4. by the way, i would note that both tools are missing something rather extremely important. those timelines really should be state machines. you should be able to have one tool where you can specify a each timeline as a statemachine that changes state when it gets the messages. ie: pre-condition/post-condition/state/message passing. examples of possible traces, make moves through the state machine. almost enough information to generate interfaces with DesignByContract.

  5. PlantUML results are awesome and flexible, but the tool itself kind of rickety at this point. On my latest macbook, I now have to run it in a Linux container running the server to get it to work; because it just silently creates no images otherwise.

      1. Interesting ... Do you mean UML diagrams or any kind of diagrams?

        How do you/they describe architecture or design? with words?

Leave a Reply

Your email address will not be published. Required fields are marked *