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

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)
• 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:

• fizzybreezy.gnuplot
• mammothb.gnuplot
• MarioSchwalbe.gnuplot

ASCII-art

• svgbob
• typograms
• markdeep
• goat
• diita
• asciitosvg
• blockdiag
• shaape

Editors:

• https://asciiflow.com/
• https://textik.com/
• https://kirilllive.github.io/ASCII_Art_Paint/ascii_paint.html

Special purpose

• wavedrom
• DrawGrammar
• state-machine-cat
• structurizr
• symbolator
• syntrax
• venn.js
• bytefield-svg
• lilypond

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

See also:

• https://xosh.org/text-to-diagram/
• https://docs.asciidoctor.org/diagram-extension/latest/

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.