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.
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 (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 (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 (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