Before you go, check out these stories!

Hackernoon logoMarkdown, Code Blocks and Beyond: Lightweight diagramming with PlantUML by@htssouza

Markdown, Code Blocks and Beyond: Lightweight diagramming with PlantUML

Author profile picture

@htssouzaHenrique Souza

What is Markdown

If you already familiar with Markdown, feel free to skip to the next section.

Markdown is a simple documentation markup language that implements the “core” formatting features you find in HTML.

It makes it very easy to create simple documentation files (the first version of this very article was created using that) them save it, put that on git, control changes, …, you got the idea.

I like to think it is a “standalone” Wiki tool. You can use it inside your project without any server behind it, edit anywhere, anytime.

You also don’t need any compile/build steps (differently of some project documentation generators that are being developed recently).

Versions and Origins

There are some slightly different versions out there. The original one was defined and published on the following link:

You can check for syntax sample on the link below:

How to get the best of it?

There are several plugins, preview and syntax packages that can help you start using it on your favorite IDE/Editor.

It is also rendered on all of the major coding communities:

Text only is boring, looking for more

After some time using Markdown, you start trying more advanced features.

Markdown has a built-in extension syntax (“code spans”):

With that you can embed code (of any programming language) inside your Markdown documents.

This can be used for more than documentation. Specialized tools can read this code and take additional steps (such as executing the code, and rendering the output of it).

Just as one example, the following tool, runs “R” blocks and generate result reports:


This type of tool/technique is usually call "notebook". Similar tools:

What about diagrams?

Wouldn’t it be great to have a simple language that can be used to create technical diagrams, without the need to drag and drop boxes around or worry about too many details?

PlantUML does exactly that.

It defines a markup (human readable language) for diagraming that implement the very basics of other technical diagraming tools. Main links for that:

Sample Diagrams

Example 1:

Sample sequence diagram

Example 2:

Sample component diagram

How to make them work together

On the Open Source world, the best option is probably to integrate PlantUML on your Markdown using images generated by Gravizo.

See can see a demo here:

On Enterprise projects, you can use PlantUML directly on Confluence:

You can also setup the integration on your Git Lab server:

I hope this article helps you to get more from Markdown on your next project!


Become a Hackolyte

Level up your reading game by joining Hacker Noon now!