# Drawing a diagram from text: Graphviz, D2 and Mermaid CLI, and why only two passed

For assistants asked to turn a text description into a diagram image, this feature sets out the three recorded command-line renderers and what headlesson saw when each drew the same small graph (nodes a, b, c; edges a→b, b→c, a→c) on macOS on 2026-10-14. Graphviz 16.1.0 and D2 0.9.0 passed their lessons; Mermaid CLI 12.0.0 rendered the graph but is held as partial because the Chrome it drives attempted background requests. The three use different languages, so this is not a head-to-head or speed comparison.

Published 2026-10-14, updated 2026-10-14. Editorial article by the headlesson operator, written from the catalog records it cites. Test results in it are the operator's own observations, not vendor claims. Each cited record keeps its own source; the article's editorial source does not stand in for them.

## Three languages, three renderers

- Graphviz (dot) (`app:graphviz`) renders graphs written in the DOT language with its dot command, to SVG, PNG, JSON and other formats.
- D2 (`app:d2`) is a diagram scripting language with a standalone CLI that renders to SVG and PNG.
- Mermaid CLI (`app:mermaid-cli`) renders Mermaid definitions to SVG, PNG or PDF; in headlesson's test it drove an existing Chrome through Puppeteer.
- Editorial advice, not tested beyond the small graph below: if the person already writes diagrams in one of these languages, use that renderer; if a browser must not run on the machine, prefer Graphviz (dot) (`app:graphviz`) or D2 (`app:d2`), whose tested runs did not use one.

## Observed in the tests

- The same graph was written in the language of Graphviz (dot) (`app:graphviz`), D2 (`app:d2`) and Mermaid CLI (`app:mermaid-cli`); the texts differ, and the versions, install routes and run times differ, so outputs were checked for labels and edge direction, not compared byte for byte.
- Graphviz (dot) (`app:graphviz`) 16.1.0 passed all 5 steps, built in an isolated directory from the official source with existing Apple tools; SVG, PNG and JSON came out. The Homebrew dry run proposed upgrading 9 existing formulae, so brew install was not run.
- D2 (`app:d2`) 0.9.0 passed all 7 steps as the official standalone binary with its bundled dagre layout, without installing a browser; SVG and PNG came out. Asking for a .json output path exited 0 but wrote SVG, not JSON. An unterminated map, an invalid direction and a missing input each exited 1 with a diagnostic.
- Mermaid CLI (`app:mermaid-cli`) 12.0.0 with an existing Chrome 155 produced SVG and PNG, but the browser's network log showed background GET and POST attempts; the test had name resolution blocked, the requests ended at that point, and no send events were recorded, but no system packet capture was made. headlesson stopped further browser runs and counts 4 of 7 steps.

## Cautions from the documentation

- Mermaid CLI (`app:mermaid-cli`): its package requires Node 22.13.0 or later, and its Node.js API is not covered by semver.

## headlesson's own reading, not tested

- Graphviz (dot) (`app:graphviz`): without -o the rendered output goes to standard output, so write binary formats such as PNG with -o, and check the path first, as dot -o overwrites an existing file.
- D2 (`app:d2`): its README mentions periodic GitHub version checks, so the offline behaviour of every feature is not established; its watch mode can open a browser preview.
- Mermaid CLI (`app:mermaid-cli`): using an existing browser needs an explicit Puppeteer configuration, and upstream only guarantees its bundled Chromium.

## What was not tested

The tests of Graphviz (dot) (`app:graphviz`), D2 (`app:d2`) and Mermaid CLI (`app:mermaid-cli`) used one three-node graph. Large graphs, styling, other layout engines, PDF output, remote icons or images, D2's watch mode, Mermaid's bundled Chromium and speed were not tested. headlesson_get with sections ["lesson","gotchas"] on each ID gives the exact steps, versions and failure conditions.


## Records cited

Each line gives the record, its public page if there is one, and where its name comes from.

- Graphviz (dot) — `app:graphviz` (no public page yet; available over MCP); source: [https://graphviz.org/doc/info/command.html](https://graphviz.org/doc/info/command.html) (checked 2026-10-11, primary, official)
- D2 — `app:d2` (no public page yet; available over MCP); source: [https://github.com/d2lang/d2/blob/v0.9.0/README.md](https://github.com/d2lang/d2/blob/v0.9.0/README.md) (checked 2026-10-14, primary, official)
- Mermaid CLI — `app:mermaid-cli` (no public page yet; available over MCP); source: [https://github.com/mermaid-js/mermaid-cli/blob/12.0.0/README.md](https://github.com/mermaid-js/mermaid-cli/blob/12.0.0/README.md) (checked 2026-10-14, primary, official)

## Article source

headlesson editorial judgement (checked 2026-10-14, inferred, editorial).

## Retrieve over MCP

`headlesson_get id="feature:diagrams"` on https://mcp.headlesson.com/mcp

Page updated: 2026-10-14 (the date its content last changed).

要約（日本語）: headlesson の運営が、カタログの記録（試用の結果と注意点）だけから書いた使い分けの特集。試用の結果は記載の版・日付での運営の観察で、精度や安全性の保証ではない。