Blog posts now support inline diagrams authored in D2¹.

Why D2

Like most people, I reached for Mermaid first. I didn’t want to add a JavaScript dependency though. D2 is a modern approach to diagrams, and has some nice things like supporting light and dark mode.

How it works

A custom MDEx² pipeline plugin walks the document AST at compile time, finds every fenced code block tagged d2, and replaces it with a %MDEx.HtmlBlock containing the rendered SVG. Failures are raised at compile time.

Usage

A basic diagram:

Diagrams support a few options in the info string. A border:

Float layout, so text flows alongside the diagram:

The float=right option floats the diagram to the right and lets text flow alongside it. Use float=left to float it to the left instead. A clear div is needed after the flowing content to stop the wrap.

And collapsible diagrams using a native <details> element:

Diagram

Implementation

The plugin is a single file — lib/personal_site/mdex_d2.ex — attached in the markdown converter before calling MDEx.to_html!/1. The d2 binary is a prerequisite (installed via brew install d2 locally, and via the install script in CI).

You can see it in use in an existing post³, and the implementation spans two commits⁴⁵.

1. D2 ↩

2. MDEx ↩

3. First shell command prediction model ↩

4. feat(blog): Add statically compiled diagrams ↩

5. build: Use Docker over Railpack ↩