Diagramming as Code in an Astro Blog: Graphviz, D2, Pikchr, and Mermaid

When I started writing posts about ML algorithms, I kept running into the same wall: I needed diagrams. Not decoration, but the kind that carry actual information, where a support vector machine without its decision hyperplane or a Viterbi algorithm without its trellis is just words pointing at something the reader cannot see.

The obvious workflow, drawing in a GUI and exporting a PNG, works once. It fails as a long-term approach because you lose the source, the image is not version-controlled in any meaningful way, and every small edit requires reopening the tool, redrawing, re-exporting, re-placing. For a blog where posts get revised, that overhead accumulates quickly.

The answer is diagramming-as-code: write a text description of the diagram, run a renderer, get an SVG. The problem is that there are several tools in this space and they are not interchangeable. They have different mental models, different strengths, and different integration stories.

I am still evaluating four: Graphviz, D2, Pikchr, and Mermaid. This post is where I am so far: what each one is, how to install it, how to integrate all four into an Astro build pipeline, and what each tool seems to be suited for. Particularly between Mermaid and D2 I have not settled on anything.

The Core Distinction

Before getting into specifics: these four tools do not all solve the same problem.

Graphviz, D2, and Mermaid are all graph tools. You describe nodes and edges, and the layout engine places everything. You give up control of exact position in exchange for automatic layout.

Pikchr is a drawing tool. You place objects at coordinates, either absolute or relative to each other. There is no layout engine. You get full geometric control and full geometric responsibility.

That distinction matters more than any feature checklist. If you need a scatter plot with a diagonal hyperplane, annotated data points at specific positions, and a margin annotation with arrows, that is a drawing problem. A graph tool will not solve it, regardless of how many features it has.

The Four Tools

Graphviz

Graphviz dates to 1991 at AT&T Bell Labs. It uses a language called DOT. You declare nodes and edges with attributes, and the layout engine figures out placement.

Several layout engines ship with it. dot produces hierarchical top-down or left-right layouts, which is the right choice for DAGs and most ML architecture diagrams. neato uses a spring model and can accept pinned coordinates, which lets you approximate geometric placement. circo and twopi handle radial layouts.

Installation is a system package, not npm:

brew install graphviz        # macOS
apt install graphviz         # Ubuntu / Debian

The CLI takes a DOT file and writes SVG:

dot -Tsvg input.dot -o output.svg

Here is the VGG-16 CNN diagram written in DOT, and what the renderer produces:

VGG-16 CNN — Graphviz — VGG-16 architecture rendered by Graphviz dot

The DOT language is deliberately minimal. You describe topology, not appearance. That minimalism is mostly a virtue for the cases it handles well, but it becomes a constraint the moment you want precise visual control or non-graph shapes.

D2

D2 was released in 2022 and is the most modern of the four. It calls itself a diagram scripting language rather than a graph language. The distinction in practice: D2 has first-class nested containers, SQL table shapes, sequence diagram support, grid layouts, and multi-line markdown-formatted labels.

Also a system install:

brew install d2
# or via the install script:
curl -fsSL https://d2lang.com/install.sh | sh

The CLI:

d2 --theme=0 --layout=elk input.d2 output.svg

Layout engines are pluggable. The default is dagre, which is the same engine Mermaid uses. The elk engine (Eclipse Layout Kernel) handles complex graphs with many cross-edges significantly better and is worth switching to. There is also a tala engine that is proprietary and requires a separate install.

The microservices architecture diagram in D2, and its output:

ML Platform Microservices — D2 — Microservices architecture rendered by D2 with ELK layout

One practical downside: every D2 SVG embeds its custom font as a base64-encoded woff blob. A single diagram adds around 25 KB before any actual drawing content. On a post with several diagrams that is noticeable.

Pikchr

Pikchr is written by Richard Hipp, the author of SQLite. It is a drawing language in the tradition of the old Unix pic preprocessor. You place shapes at coordinates or relative to previous objects. There is no layout engine.

There is no Homebrew formula and no npm package. You build it from source:

git clone https://sqlite.org/pikchr pikchr
cd pikchr
make

The binary reads a .pikchr file and writes SVG to stdout:

./pikchr --svg-only input.pikchr > output.svg

The SVM diagram, which draws the decision hyperplane, margin planes, and scatter points at precise coordinates:

SVM — Pikchr — SVM geometry rendered by Pikchr — scatter plot with exact coordinate placement

The build-from-source requirement is real friction. It means documenting the build steps for any CI environment, and the binary path is machine-specific. If you are the only person building the site it is manageable. If not, it becomes a dependency management problem.

What Pikchr buys you in exchange is geometric expressiveness. The SVM diagram in this blog, the one with the decision hyperplane at a specific angle, support vectors at precise scatter positions, dashed margin planes, and a two-headed arrow annotating the margin width, is a Pikchr diagram. That specific diagram cannot be produced by Graphviz, D2, or Mermaid. Those tools lay out graphs. They do not draw geometry.

Mermaid

Mermaid is the most widely used of the four. It runs in the browser as a JavaScript library, which makes it the native diagram tool for GitHub, GitLab, Notion, and Obsidian. For a static site there is also a CLI (@mermaid-js/mermaid-cli, command mmdc) that renders SVG server-side via Puppeteer.

Installation is npm:

npm install --save-dev @mermaid-js/mermaid-cli

The CLI:

mmdc -i input.mmd -o output.svg --backgroundColor transparent

The --backgroundColor transparent flag matters if your site is not white. Without it you get a white rectangle behind every diagram.

Mermaid supports the most diagram types of any tool here: flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, git graphs. Each has its own syntax.

The sequence diagram support is the strongest of any of the four tools. Loop blocks, alt/else branches, and notes are native constructs. Here is the ML training loop sequence diagram:

ML Training Loop — Mermaid — Training loop sequence diagram rendered by Mermaid — loop and alt blocks are native syntax

D2 has sequence diagram support but loop and alt blocks do not exist in its syntax. You annotate individual messages instead, which loses the structural grouping.

Feature Comparison

	Graphviz	D2	Pikchr	Mermaid
Language type	Graph (DOT)	Diagram scripting	Drawing / geometry	Diagram scripting
First released	1991	2022	2021	2014
Installation	System package	System package	Build from C source	npm
Output formats	SVG, PNG, PDF, many	SVG, PNG	SVG	SVG, PNG
Layout engines	dot, neato, fdp, circo, twopi	dagre, elk, tala	None (manual)	dagre (fixed)
Auto-layout	Yes	Yes	No	Yes
Nested containers	Subgraphs (limited)	First-class	Manual	Subgraphs
Flowcharts	Yes	Yes	Manual	Yes (native)
Sequence diagrams	No	Partial (no loop/alt)	No	Yes (full)
Class / ER diagrams	Manual	No	No	Yes (native)
Geometric drawing	Via neato (awkward)	No	Yes (native)	No
Custom colors	Yes	Yes	Yes	Yes (classDef)
Multi-line labels	Limited	Markdown-formatted	Yes	HTML in quotes
SVG file size	Small	Large (embedded font)	Small	Medium
Browser rendering	No	No	No	Yes (JS library)
GitHub native	No	No	No	Yes
Documentation	Good	Good	Minimal	Excellent
Community	Large, mature	Small, growing	Very small	Very large
Active development	Maintenance mode	Active	Active	Active
Diagram types	Flowcharts, DAGs	Flowcharts, seq (partial), containers	Drawing only	Flowcharts, seq, class, ER, state, Gantt, git

Integrating All Four into Astro

The approach I use is a pre-build script that renders every source file to SVG. The SVGs land in public/ and Astro serves them as static assets. No Astro plugin, no remark integration, no runtime rendering.

Directory layout

technical-diagrams/       ← source files, not served
  graphviz/
    svm.dot
    cnn.dot
  d2/
    microservices.d2
    transformer.d2
  pikchr/
    svm.pikchr
  mermaid/
    training-sequence.mmd
    microservices.mmd

public/
  technical-diagrams/     ← rendered SVGs, served at /technical-diagrams/
    graphviz/
    d2/
    pikchr/
    mermaid/

Source files live at the project root, outside both src/ and public/. They are the version-controlled source of truth. The rendered SVGs in public/ are build artifacts.

The build script

scripts/build-diagrams.mjs globs for source files, skips any whose SVG is already newer, and dispatches to the right renderer:

import { execSync, spawnSync } from 'child_process';
import { existsSync, mkdirSync, statSync, writeFileSync } from 'fs';
import { globSync } from 'glob';
import { basename, dirname, join } from 'path';

const SRC = 'technical-diagrams';
const OUT = 'public/technical-diagrams';
const FORCE = process.argv.includes('--force');

function newerThan(src, out) {
  if (!existsSync(out)) return true;
  return statSync(src).mtimeMs > statSync(out).mtimeMs;
}

// Graphviz
for (const src of globSync(`${SRC}/graphviz/*.dot`)) {
  const out = join(OUT, 'graphviz', basename(src, '.dot') + '.svg');
  if (FORCE || newerThan(src, out)) {
    mkdirSync(dirname(out), { recursive: true });
    execSync(`dot -Tsvg -o ${out} ${src}`);
  }
}

// D2
for (const src of globSync(`${SRC}/d2/*.d2`)) {
  const out = join(OUT, 'd2', basename(src, '.d2') + '.svg');
  if (FORCE || newerThan(src, out)) {
    mkdirSync(dirname(out), { recursive: true });
    execSync(`d2 --theme=0 --layout=elk ${src} ${out}`);
  }
}

// Pikchr (writes to stdout)
for (const src of globSync(`${SRC}/pikchr/*.pikchr`)) {
  const out = join(OUT, 'pikchr', basename(src, '.pikchr') + '.svg');
  if (FORCE || newerThan(src, out)) {
    mkdirSync(dirname(out), { recursive: true });
    const result = spawnSync('./pikchr', ['--svg-only', src], { encoding: 'utf8' });
    writeFileSync(out, result.stdout);
  }
}

// Mermaid
const MMDC = 'node_modules/.bin/mmdc';
for (const src of globSync(`${SRC}/mermaid/*.mmd`)) {
  const out = join(OUT, 'mermaid', basename(src, '.mmd') + '.svg');
  if (FORCE || newerThan(src, out)) {
    mkdirSync(dirname(out), { recursive: true });
    execSync(`${MMDC} -i ${src} -o ${out} --backgroundColor transparent`);
  }
}

Add it to package.json:

{
  "scripts": {
    "diagrams": "node scripts/build-diagrams.mjs",
    "diagrams:force": "node scripts/build-diagrams.mjs --force",
    "dev": "npm run diagrams && astro dev",
    "build": "npm run diagrams:force && astro build"
  }
}

Referencing diagrams in MDX

Once the SVGs are in public/, you reference them as ordinary images:

![SVM — decision boundary and support vectors](/technical-diagrams/pikchr/svm.svg)

No import, no component, no plugin. The SVG is a static file at a stable URL. It works in RSS, it is cacheable, and it can be linked to directly.

The alternative, using a remark plugin like astro-d2 to render D2 fenced code blocks inline at build time, keeps diagram source and explanation in the same file. That is genuinely convenient for short diagrams that belong to one post. The tradeoff is that you cannot reuse a diagram across posts and you cannot run the renderer separately from the Astro build. For now I prefer the explicit pipeline.

What Each Tool Is Actually Good At

Graphviz: structure that has a natural rank

Graphviz is best when the diagram has a clear directionality and you want the layout engine to enforce it. A neural network architecture, a compilation pipeline, a dependency tree, a Markov chain where arrows point forward in time. The dot engine’s rank-based placement produces clean results for these with almost no effort.

It is the wrong tool when you want visual control. The output can look mechanical, and adjusting layout requires indirect workarounds like invisible edges or rank constraints. Anything that is not fundamentally a graph is a fight.

D2: architecture diagrams with nested structure

D2 shines on the kind of diagram that describes a system: a microservices architecture, an ML platform with multiple layers, an infrastructure diagram where things live inside other things. The nested container syntax with named labels, the ability to connect nodes across container boundaries, and ELK’s edge routing all combine well for this.

Compared to Mermaid on the same microservices diagram, D2 with ELK routes edges more cleanly in dense graphs but produces a taller, more vertical layout. Mermaid’s dagre keeps things horizontal and compact. For that specific use case Mermaid actually won.

The embedded font is a real cost. It is worth knowing about before you commit to D2 for a diagram-heavy page.

Pikchr: geometric and mathematical figures

Pikchr is the only tool here that can produce a true geometric diagram: axes, plotted points, lines at angles, annotated distances. For ML content specifically, the kinds of figures that appear in textbooks, hyperplane geometry, information-geometric visualizations, filter response diagrams, Pikchr is the only viable option among these four.

The cost is full manual placement. And the build-from-source install means you need to commit the binary path to your build script and document the build process for anyone else who runs it.

Mermaid: sequence diagrams and general flowcharts

Mermaid is the most versatile general-purpose tool here. For sequence diagrams with loops and conditional branches it has no competition. For straightforward flowcharts and architecture diagrams where the layout does not need to be tuned, it is fast to write and produces clean output.

The npm installation is the lowest friction of any of the four, and the Puppeteer-based CLI works out of the box without additional system configuration.

The Mermaid vs D2 Question

I am still not decided between these two for the general case. Both handle flowcharts and architecture diagrams. The cases where they diverge:

Mermaid is the better choice when:

The diagram is a sequence diagram with loop or alt blocks
The layout needs to be compact and horizontally layered
The diagram needs to be readable outside the blog (GitHub README, shared link)
Minimal setup friction matters

D2 is the better choice when:

The diagram has deeply nested containers with internal edges
The graph is dense enough that ELK’s routing is worth the larger SVG
You want clean markdown-formatted multi-line labels without HTML in the source
You are willing to live with the embedded font overhead

In practice I have ended up using them for different diagram types rather than picking one. Mermaid for sequence diagrams, D2 for infrastructure and architecture layouts, Pikchr for anything geometric, Graphviz for DAGs and dependency structures.

Installation Summary

# Graphviz
brew install graphviz        # macOS
apt install graphviz         # Ubuntu

# D2
brew install d2
# or: curl -fsSL https://d2lang.com/install.sh | sh

# Pikchr (build from source)
git clone https://sqlite.org/pikchr pikchr
cd pikchr && make
# binary at ./pikchr — note the path in your build script

# Mermaid CLI
npm install --save-dev @mermaid-js/mermaid-cli

Quick version check:

dot -V          # graphviz 12.x
d2 --version    # v0.7.x
mmdc --version  # @mermaid-js/mermaid-cli 11.x

Pikchr has no version flag. Run ./pikchr --help to confirm the binary works.