Simple diagrams in docs

Tooling
, ,
1

I would like to include a simple diagram (= boxes connected by arrows) in the docs of a Julia package, generated by Documenter.jl as usual.

I am not sure what my best option is.

I can just write it in whatever markup I like, render it on my machine to an SVG file and include it as an image. Pro: robust, no hassle. Cons: need to remember to regenerate and commit if updated.

I have seen DocumenterDiagrams.jl, powered by Kroki.jl. But currently kroki.io is down, and I would not want to call a web service each time the page is viewed.

Is there an in-Julia solution for rendering diagrams?

1 Like
2

For simple diagrams I like using mermaid: Creating diagrams - GitHub Docs

and the plugin:

4 Likes
3

I use https://asciiflow.com/ all the time, these have the nice property that you can copy-paste them everywhere, on slack, discourse, dostrings, documenter, email, you name it.

image
image1698×1489 358 KB

Here are a few examples rendered by Documenter

10 Likes
4

I’ve added a simple graphviz block in the Makie docs which should work with any Documenter based system

used here for example

1 Like
5

that option does not seem to work with darkmode?

image
image928×731 43.5 KB

6

I didn’t pay attention to that at all, maybe one could hack something together to export twice with different color schemes

7

DocumenterVitepress will already support this (but only for PNGs and JPGs at the moment):

although I should probably rewrite that code to be more reasonable…

2 Likes
8

Out of the various great suggestions, this is the closest to my heart, so I am marking it as the solution.

I love this approach since it is just text in a ``` block, requires absolutely no tooling whatsoever to render, is completely future-proof, and there are various Emacs modes doing this too, eg uniline. Thanks!

3 Likes