15 Mermaid and Graphviz: Creating Diagrams with Text
Guiding Question: Can diagrams be written instead of drawn?
When most people think of diagrams, they imagine drawing.
Boxes are dragged onto a canvas.
Arrows are connected with a mouse.
Shapes are resized until everything appears balanced.
This visual approach has become so familiar that it seems almost inevitable.
Yet what if diagrams could be described rather than drawn?
What if a flowchart, an organizational chart, or a network graph could be written as plain text in much the same way that Markdown describes a document?
At first, the idea sounds surprising.
In practice, it has transformed the way many people create and maintain technical diagrams.
15.1 From Drawing to Description
Traditional diagramming software stores the appearance of a diagram.
The exact position of every shape.
The coordinates of every line.
The colour of every object.
Text-based diagram languages take a different approach.
Instead of recording appearance, they describe relationships.
A flowchart might simply state:
mermaid id="fobitj" flowchart LR A --> B B --> C
The software determines how best to arrange the diagram.
Just as HTML separates structure from presentation, text-based diagram languages separate relationships from layout.
15.2 Graphviz
One of the earliest and most influential text-based diagram systems is Graphviz.
Originally developed to visualize graphs and networks, Graphviz allows authors to describe nodes and the relationships between them.
A simple graph might appear as:
dot id="7nbhqm" digraph { A -> B B -> C }
From these few lines, Graphviz generates a complete diagram.
The author describes the connections.
Graphviz calculates an appropriate layout.
This automation makes Graphviz especially valuable for large and complex diagrams where manual positioning would become tedious.
15.3 Mermaid
While Graphviz specializes in graph visualization, Mermaid was designed with modern documentation in mind.
Its syntax supports many common diagram types, including:
- flowcharts
- sequence diagrams
- class diagrams
- state diagrams
- entity-relationship diagrams
- Gantt charts
- journey maps
- mind maps
Because Mermaid is written as plain text, diagrams integrate naturally with documentation systems, knowledge bases, and version control.
Many modern publishing platforms now render Mermaid diagrams automatically.
15.4 Diagrams as Source Code
Perhaps the most important idea behind Mermaid and Graphviz is that diagrams become source documents rather than graphical objects.
A diagram can now be:
- searched
- version controlled
- reviewed
- generated automatically
- edited collaboratively
- embedded within documentation
Small changes often require editing only a few lines of text rather than rearranging dozens of graphical objects.
For technical documentation, this represents a significant improvement in maintainability.
15.5 Reproducibility
Another advantage of text-based diagrams is reproducibility.
Because the diagram is generated from its textual description, the same source always produces the same result.
The risk of accidental changes introduced through manual editing is greatly reduced.
This philosophy closely resembles ideas encountered throughout this primer.
Describe the structure.
Allow software to generate the presentation.
15.6 Documentation and Visualization
Mermaid and Graphviz fit naturally into modern documentation workflows.
A software manual can contain executable code, explanatory text, mathematical notation, citations, and diagrams—all stored as plain text.
Version control records changes to every component.
Publishing systems generate the final output automatically.
The distinction between writing and illustration becomes much smaller than it once was.
15.7 Beyond Boxes and Arrows
Although flowcharts are common examples, text-based diagram languages extend much further.
Graphviz excels at representing networks and complex relationships.
Mermaid supports software architecture, project planning, database models, timelines, and numerous other visual forms.
Other systems, such as TikZ, provide exceptionally sophisticated graphical capabilities within the TeX ecosystem, particularly for scientific and mathematical publications.
Together, these tools demonstrate that visual communication can often be expressed just as effectively through carefully structured text.
15.8 The Broader Philosophy
Mermaid and Graphviz illustrate one of the deepest ideas explored throughout this book.
Plain text is not limited to prose.
It can describe:
- documents
- websites
- books
- mathematical notation
- software documentation
- technical manuals
- presentations
- and now diagrams.
Once information is expressed structurally, software can determine how best to present it.
This recurring principle connects every markup language encountered in this part of the primer.
15.9 Lessons for the Textsmith
Text-based diagrams remind us that markup languages are ultimately languages of ideas.
The author does not draw every line manually.
Instead, the author describes concepts and relationships.
The computer performs the mechanical work of arranging the visual presentation.
This approach improves consistency, simplifies maintenance, and integrates naturally with modern publishing systems.
Most importantly, it demonstrates once again that plain text is capable of expressing far more than words alone.
15.10 Key Ideas
- Mermaid and Graphviz describe diagrams using plain text.
- They emphasize relationships rather than manual positioning.
- Text-based diagrams integrate naturally with documentation, version control, and publishing workflows.
- Diagram source files remain searchable, maintainable, and portable.
- Graphviz specializes in graph visualization, while Mermaid supports a wide variety of documentation-oriented diagrams.
- TikZ extends similar ideas within the TeX ecosystem for high-quality scientific graphics.
- Diagram markup demonstrates that structured plain text can represent visual as well as textual information.
With this chapter, we conclude our exploration of markup languages.
In the next part of The Textsmith Primer, we turn our attention from describing information to manipulating it.
We discover how searching, filtering, transforming, and analysing plain text gave rise to one of the most productive traditions in computing: text processing.