Text to diagram

Table of Contents

aka diagrams as code

I dreamt about it for a long time. Idea is to allow to express diagrams with a text, this way you can draw diagram while you are writing you markdown file. Without need to switch to another tool. And this diagram becomes part of the document and can be stored in git.

Now when Hugo supports render hooks for code blocks and in MDX you can do this too (to use with Astro, etc.) it’s time to revisit the subject.

Categories #

Before we move on let’s introduce some kind of categorisation of tools.

Types #

Declarative - when you have specific language for the job. You express what you want to get and it’s up to the tool to figure out how to draw it
- Examples: Mermaid, Graphviz, d2lang
Imperative - more involved approach, you need to specify how to draw the diagram
- Examples: ?
- Note: python + Matplotlib, for example. also in this category, but if we go that far we will reinvent Jupyter. So let’s leave it out
ASCII-art - you de-facto drawing, but with text. Tool just responsible for making it look nicer than terminal output
- Examples: svgbob, typograms, markdeep, goat

Features #

output format: svg, png (or any other raster image format), ASCII-art, html + css + js
integration: library, cli, web browser
supported diagrams: network/graph, flowchart, UML and many more
theming: if you have to hardcode colours in the diagram or you can configure it later, for example to support dark theme
other: code highlighting plugin for editor, auto-formatter/pretty-printer, support for icons/images, support for embedding html/markdown/LaTeX, etc

Tools #

Names	Type	Integration	Formats	Supported diagrams
mermaid	Declarative	browser*	SVG	Flowchart, UML, ER, Gant…
graphviz	Declarative	CLI, library	SVG, raster	Graphs (flowchart, network, etc)
d2lang	Declarative	CLI (go)	SVG, raster…	Flowchart, UML, ER…
pikchr	?	CLI, library	SVG	Kind of anything
Diagon	Declarative	CLI, library	ASCII-art	Flowchart, Sequence…
PlantUML	Declarative	CLI	SVG, raster, ASCII-art	UML…
gnuplot	?	CLI	SVG, raster, ASCII-art	plots
Tikz	?	LaTeX*	PDF*	anything

This is birdeye overview. There are nuances. I didn’t include some libraries that:

has very narrow use-case (only one type of digram)
are less popular or not supported (abandonware)

Mermaid #

Most popular, because it was adopted by github
Works only in the browser. There is a cli, but it just a hack with headless browser (puppeteer)
- pintora may be a good alternative
Theme-able
syntax highlightning

Graphviz #

Mature and wide-spread. I think, it was number one for graphs (flowchart, network, DAG) before github integrated mermaid
Originally CLI tool, but there are as well libraries, for example WASM-based, which allows to use Graphwiz on the server and in the browser
syntax highlightning

d2lang #

Wants to take over the world
Originally CLI tool, but there is an attempt to convert to WASM library
It worth to mention that it packs headless browser (playwright)
Theme-able
syntax highlightning

Pikchr #

“ PIC-like markup language for diagrams in technical documentation”
To me it feels more on declarative side, but you can do some imperative things as well
There is WASM library and go port
syntax highlightning

Diagon #

“Diagon is an interactive interpreter. It transforms markdown-style expression into an ascii-art representation.”
It is the only one option on the list which outputs (only) ASCII-art. But you can feed it to another tool which will convert it to SVG
There is WASM library, but it’s not distributed as npm package

Tikz #

The most famous option between people who use LaTeX
I can’t tell if this more declarative or imperative approach (kind of both)
There is a project which compiles Tikz to WASM ( demo), but it’s not distributed as npm package

gnuplot #

This is the only one solution on the list which focuses solely on plots. There are a lot of plot libraries and I don’t want to list them all here. The difference from other solutions:

It is standalone, while other solutions are DSLs/libraries inside bigger language, for example matplotlib “requires” python
it is CLI, where is many other solutions are GUI

One way or another I felt like I need to include at least one of those on the list. Originally written in C, so there is a chance of porting it to WASM (see also MobileGnuplotViewerQuickWASM)

I can’t tell if this more declarative or imperative approach (kind of both)

Syntax highlightning:

ASCII-art #

Editors:

Special purpose #

Other #

Other tools (I’m pretty sure there are much more projects which I’m not aware of):

penrose. This one is interesting - I need to read more about it
vega-lite
mscgen
- mscgen_js
flowchart.js
js-sequence-diagrams
kroki
dbml-renderer
dpic
erd
actdiag
nomnoml
UMLet

Instead of conclusion #

I’m looking for solution:

to embed diagrams in markdown file (inside fenced code block)
ideally it should be possible to generate on the server (during conversion of markdown to HTML)
ideally it should generate SVG, If we inline SVG (instead of using <img>) it can support
- dark mode via classes or css variables
- it can be animated
- it can contain html links (<a>)
- you can use Cmd + F to search text in it
- we can add zoom/pan to it as in github
- sometime you need to have standalone file as well, which you can include as image for crossposting
it should be lightweight (so no headless browsers)
In some cases it make sense to generate visualisation on the client side (in the browser), for example:
- fractals with infinite zoom
- interactive visualisations, like in g9 or Road to Reality Essays. In this case they should use high performance solutions (canvas or WebGL)

Diagrams that I’m interested in:

graphs (aka network, flowchart, DAG, etc.)
- Hasse diagrams
- subway-scheme like diagrams. For example see: gitgraph, metrosets
Euler diagrams (which are often confused with Venn)
xkcd-style plots
sankey diagrams

One more twist to this story. Because those diagrams can be represented as text you can use GhatGPT to generate diagrams.

Read more: Astro diagrams, BEOE