{
 "kind": "feature",
 "id": "feature:diagrams",
 "url": "https://headlesson.com/features/diagrams",
 "title": "Drawing a diagram from text: Graphviz, D2 and Mermaid CLI, and why only two passed",
 "summary": "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",
 "body": "# Three languages, three renderers\n\n- app:graphviz renders graphs written in the DOT language with its dot command, to SVG, PNG, JSON and other formats.\n- app:d2 is a diagram scripting language with a standalone CLI that renders to SVG and PNG.\n- app:mermaid-cli renders Mermaid definitions to SVG, PNG or PDF; in headlesson's test it drove an existing Chrome through Puppeteer.\n- 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 app:graphviz or app:d2, whose tested runs did not use one.\n\n# Observed in the tests\n\n- The same graph was written in the language of app:graphviz, app:d2 and 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.\n- 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.\n- 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.\n- 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.\n\n# Cautions from the documentation\n\n- app:mermaid-cli: its package requires Node 22.13.0 or later, and its Node.js API is not covered by semver.\n\n# headlesson's own reading, not tested\n\n- 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.\n- 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.\n- app:mermaid-cli: using an existing browser needs an explicit Puppeteer configuration, and upstream only guarantees its bundled Chromium.\n\n# What was not tested\n\nThe tests of app:graphviz, app:d2 and 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.\n",
 "refs": [
  {
   "id": "app:graphviz",
   "name": "Graphviz (dot)",
   "source": {
    "source": "https://graphviz.org/doc/info/command.html",
    "checked": "2026-10-11",
    "certainty": "primary",
    "by": "official"
   }
  },
  {
   "id": "app:d2",
   "name": "D2",
   "source": {
    "source": "https://github.com/d2lang/d2/blob/v0.9.0/README.md",
    "checked": "2026-10-14",
    "certainty": "primary",
    "by": "official"
   }
  },
  {
   "id": "app:mermaid-cli",
   "name": "Mermaid CLI",
   "source": {
    "source": "https://github.com/mermaid-js/mermaid-cli/blob/12.0.0/README.md",
    "checked": "2026-10-14",
    "certainty": "primary",
    "by": "official"
   }
  }
 ],
 "article_source": {
  "source": "headlesson editorial judgement",
  "checked": "2026-10-14",
  "certainty": "inferred",
  "by": "editorial"
 },
 "note": "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.",
 "mcp_get": "headlesson_get id=\"feature:diagrams\"",
 "page_updated": "2026-10-14"
}