Diagrams As Code

Depending on when you started diagramming, you may not have heard of diagrams as code. Before the likes of PlantUML and MermaidJS diagrams were exclusively drawn using tools such as Visio. In recent years, better visual tools such as draw.io have emerged, but all visual diagramming tools all have one problem in common.

The Problem With Visual Diagramming Tools

What's the problem with visual diagramming tools, you ask? For starters, when you want to share the diagram, or render it on a web page, you have to export it from the tool. At that point, the source and rendered diagram are disconnected. If anyone wants to update the diagram in future, they have to know where to find the source. All too many times, I've seen someone leave a company, and the source code for the diagram gone with them.

Secondly, they are usually stored outside of version control, and cannot be stored as a diagram in Markdown. Typically, they are stored on some sort of cloud storage, such as Google Drive. Most of the time, they are never committed to version control, which also means changes are not reviewed.

And lastly, similarly to the last point, the underlying format these visual tools store the diagrams in is completely undiffable. If you take a look at a draw.io save file, it's like looking at a huge amount of base64 encoded strings.

So, if visual tools aren't cutting it in 2023, what does diagrams as code have to offer?

The Benefits Of Diagrams As Code

I don't know if PlantUML was the first, but it was the first tool I used that allowed you to define diagrams using syntax similar to Markdown. In short, you could create diagrams using simple syntax and use PlantUML's Java-based renderer to generate images.

It gained a reasonable amount of adoption, but unfortunately it never really hit the mainstream. In my opinion, that's because exporting out of PlantUML needed Java, which isn't readily available on the web. If you want to put diagrams in Markdown, it's not possible without complex parsing, or custom tooling on merge.

Over 10 years later though, MermaidJS was born, and it too is a tool promoting diagrams as code. It uses similar syntax to PlantUML, but it was written entirely in JavaScript. At this point, you might be thinking "so what?", or perhaps worse, thinking how JavaScript could possibly be an improvement on Java.

The big deal is that JavaScript runs pretty much anywhere these days, including directly in the browser. In 2022, MermaidJS hit the big time when GitHub announced you could now use MermaidJS to create diagrams in Markdown.

This meant you could write your diagrams as code in your README, in your documentation, anywhere you liked on GitHub. You no longer needed to use a visual tool, export, and upload to GitHub manually. Instead, you embed the Mermaid markup in a Markdown file, and when viewed, GitHub will render the diagram as an image.

Furthermore, it solves the problem of storing it under version control, you now have a single source of truth for that diagram. And, of course, it's completely diffable as Mermaid markup is written in simple Markdown-like syntax.

Here's what MermaidJS' diagrams as code looks like:

          flowchart
            A-- "description" -->B
        

It supports many types of diagrams, including the major ones from UML, along with a versatile flowchart, and more recently native support for the C4 model.

We can also render that diagram easily in any web page, like so:

            flowchart
                A-- "description" -->B
        

That's not an image I've exported, it's rendered in real time when you view this page. The same happens on GitHub too, as well as other tools such as GitLab.

Putting diagrams in Markdown is a huge win for diagramming in general, but also a huge selling point for diagrams as code. No more having to find the source for a diagram, no more manual exporting of images, no more hard-to-review diagrams, just simple markup leveraging diagrams as code.

Learn The Full Power Of Diagrams As Code

This was an overview of what diagrams as code is, and how to put diagrams in Markdown.

Want to learn more? I cover how to create a wide range of diagrams and their associated use cases, in my book: Creating Software Using Modern Diagramming Techniques, published via The Pragmatic Programmers.