13,381 reads

Markdown, Code Blocks and Beyond: Lightweight diagramming with PlantUML

by Henrique SouzaNovember 15th, 2017

Too Long; Didn't Read

<em>If you already familiar with Markdown, feel free to skip to the next section.</em>

Companies Mentioned

featured image - Markdown, Code Blocks and Beyond: Lightweight diagramming with PlantUML

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:

Daring Fireball: Markdown_The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a…_daringfireball.net

You can check for syntax sample on the link below:

https://daringfireball.net/projects/markdown/syntax

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”): https://daringfireball.net/projects/markdown/syntax#precode

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:

R Markdown_Turn your analyses into high quality documents, reports, presentations and dashboards with R Markdown. Use a productive…_rmarkdown.rstudio.com

Examples: http://rmarkdown.rstudio.com/gallery.html

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?