Tentacle Labs Blog

Markdown is a great format. I use it a lot for documentation. It’s much easier to keep documentation up to date by keeping it close to the code. Sure, Markdown has limited formatting features, but it helps to focus on the essential part, the content. But there is one feature missing: Drawing diagrams.

When it comes to documentation, the saying “a picture is worth a thousand words” is simply true. When I write technical software documentation or design documents such as ADRs, I often visualize the architecture in component, flow, or entity diagrams. You could draw these diagrams in any tool, export them as an image file, and include them with your Markdown. But architecture is never static, it always evolves over time, and so do your diagrams. Having static image files makes this difficult, you can’t open them anymore with the original editor, you have to store an additional file with the metadata. Let me introduce you to three tools that I use regularly:

Mermaid

The Mermaid open source project is best described as “diagrams as code”. It’s a true extension to Markdown, allowing you to edit diagrams directly in your Markdown files. Diagrams are embedded into your Markdown using code fences: ```mermaid A wide range of diagram types are supported: Flowcharts, class diagrams, entity diagrams, and many more… Each diagram type has its own syntax, but they are easy to learn.

One disadvantage of Mermaid is that you always need an extension to view the diagrams. GitHub has built-in support, so if you use GitHub, it’s a perfect match. But there are also extensions for IDEs, I already used the VSCode extension.

I think Mermaid is a great choice if you need to draw more complex diagrams that follow a specific diagram type, but still want to be able to easily modify them in code.

Diagrams.net

Diagrams.net, also known as draw.io, is a visual editor for drawing visualizations. If you like WYSIWYG, you will love this! You can do anything you need, draw shapes, change styling, add text, you name it. It also comes with a large library of symbols and shapes, including entity relationship diagrams and UML diagrams.

But the best trick is yet to come: While it produces SVG or PNG files that you can reference from your Markdown, you can also embed metadata into these files. The metadata allows you to import the files back into Diagrams.net later. So you have the best of both worlds, storing a single file and being able to view the diagrams without an additional viewer.

Besides the web app, you can also use the standalone desktop client, or the VSCode extension. Everything in diagrams.net is open source!

I think Diagrams.net gives you a lot of freedom. It’s the best choice for large and complex diagrams.

ASCIIFlow

ASCIIFlow is for the purists, it uses only low-tech ASCII characters to render diagrams It comes with a nice web-based editor that allows you to draw basic shapes and lines. Finally, you can export your drawing as ASCII text and embed it with a code block (and import it again).

Sometimes I would like to see more kinds of shapes like circles or boxes with a different border, and certainly Unicode would have a lot of different characters for that. But wasn’t my request for a tool that was simple and not a distraction from the content? You can always fall back to the freeform drawing tool. I like ASCIIFlow for entity, component, or context diagrams and it’s often my first choice. You can also draw more complex diagrams like flowcharts, but it’s a lot of manual work. ASCIIFlow is open source, if you want to improve it, go to its GitHub repository.

                                        ┌──────────────────────────┐
                             Yes        │                          │          No
                             ┌──────────┤ Will the content change? ├────────────┐
                             │          │                          │            │
                             │          └──────────────────────────┘            │
                             ▼                                                  ▼
                 ┌──────────────────────────┐                        ┌────────────────────┐
       WYSIWYG   │                          │      As code           │                    │
       ┌─────────┤ How to edit the diagram? ├────────────┐           │ Embed static image │
       │         │                          │            │           │                    │
       │         └──────────────────────────┘            │           └────────────────────┘
       ▼                                                 ▼
┌──────────────┐                            ┌───────────────────────┐
│              │                  Yes       │                       │        No
│ diagrams.net │                  ┌─────────┤ Is it ok to install a ├─────────┐
│              │                  │         │ separate viewer?      │         │
└──────────────┘                  │         │                       │         │
                                  │         └───────────────────────┘         │
                                  ▼                                           ▼
                          ┌───────────────┐                           ┌──────────────┐
                          │               │                           │              │
                          │    Mermaid    │                           │  ASCIIFlow   │
                          │               │                           │              │
                          └───────────────┘                           └──────────────┘
A diagram using ASCIIFlow

The next time you want to draw a diagram in your Markdown file, I hope these tools will help you.