Root > Articles > Writing >

Adding little diagrams to my posts

Jan 12, 2023 • Yousef Amar • 2 min read

I made a post earlier today that had a little diagram in it. I made this diagram with the help of ChatGPT by having it write a DOT description of the diagram I wanted ("connect A with B with an arrow"), which also allowed me to learn the basics of DOT without sifting through their unfortunately awful documentation. This can then be turned into an actual diagram with Graphviz. There's an online playground here.

I used this because 11ty (which I use to turn markdown into these posts) and Obsidian (which I use to actually write the posts) both have plugins that render these. The Obsidian one is pretty cool and you can use it to do live preview like the playground above. When I wrote the previous post, I couldn't get the 11ty one to work properly, so I just included it as a normal SVG. But now I managed to get it to work and I'm relatively happy with it. It's a little finicky to be honest, e.g. this is the DOT that created the diagram from my previous post.

digraph {
  node [shape=rectangle color="#a9b0b3" fontcolor="#a9b0b3"]
  edge [color="#a9b0b3" fontcolor="#a9b0b3"]
  Markdown [shape=none]
  Markdown -> "11ty"
  "11ty" -> "" [label="h-feed (HTML)"]
  "" -> "Most feed readers" [label="Atom"]
  "" -> "Weekly digest" [label="Atom"]
  "Weekly digest" -> "" [label="E-mail"]
  "Weekly digest" -> "E-mail inboxes" [label="E-mail"]
    rank = same;
    "" -> "Most feed readers" [label="Atom    "]
    "E-mail inboxes" -> "" [style=invis]

I don't like hardcoding the colours, and the extra cruft that I'd like to set as defaults somewhere, but I think I have some potential solutions for that. The above creates:

%0MarkdownMarkdown11ty11tyMarkdown->11tygranary.iogranary.io11ty->granary.ioh-feed (HTML)Most feed readersMost feed>Most feed readersAtomWeekly digestWeekly>Weekly digestAtomkill-the-newsletter.comkill-the-newsletter.comWeekly digest->kill-the-newsletter.comE-mailE-mail inboxesE-mail inboxesWeekly digest->E-mail>Most feed readersAtom    

The resulting SVG is inline; there's no file output. I'm not sure yet how this will behave in feed readers, but let's see. One small annoyance is that the Obsidian plugin uses dot code blocks, while the 11ty plugin uses graphviz code blocks. This has the side effect that I actually see the above code and diagram reversed. I suppose I could tweak the plugins to be the same (open source), but for now I'm ok editing with dot and changing it to graphviz when I'm done. Anyway, this is ideal for quick and easy diagrams, but for anything more complicated, I would use yEd.

Alternatively, there's a / plugin for Obsidian, which lets you edit SVGs directly with the option to use their simplified interface directly. This is much more flexible as you can do a lot more and aren't constrained by DOT, e.g. freehand drawing. Plus the output is very portable (literally SVGs that you can go and edit some more in Inkscape). The downside is that you need a computer and a mouse to really use it, rather than just type everything, meaning you also can't edit these on mobile (especially because that plugin doesn't support mobile). Here's an example of a small diagram made with the plugin:

Going forward, I might use both depending on the situation!