Declarative Diagramming with Mermaid

Diagrams are an important part of the specification and documentation of software or other technological and societal artefacts. Many types of diagrams have been used, from flowcharts in the 1920’s, to Nassi-Shneiderman diagrams, UML, Entity Relation Diagrams, and C4 ion the 2010’s. There are a plethora of diagramming tools available, most of which provide a boxes-and-lines graphical user interface to draw diagrams.

In this presentation we focus on text-based diagramming tools, specifically Mermaid. Tools like Mermaid have the advantage of being declarative; The user specifies what is in the diagram, not how this will be graphically represented. In this way, making diagrams becomes quicker, diagrams can be more easily modified, and can be processed by software.

We will look at some diagram types and how to specify them in Mermaid. There are several tools available to transform Mermaid syntax into graphical output, both on-line and off-line, and we will see how to use these.

With Mermaid, diagrams become a powerful tool for software analysis, providing insights that are hard to get from code in a visual way. We will show an example of this, debugging and optimising a web component by generating a diagram for the function call graph.

Conversely, it is possible to generate code from diagrams. We intend to show an example of this as well. Depending on whether the singularity has already happened in November, we will see how a LLM can generate Mermaid diagrams.