← All updates

Graphviz DOT and declarative graph diagrams in Markdown

Markdown documents can now embed Graphviz DOT diagrams — plus a declarative YAML graph block for data-shaped diagrams — rendered as crisp native PDF vector graphics like every other diagram type.

markdowndiagramsdotgraphviz

POST /api/v1/md (and the CLI and blog renderer) now understands two more fenced block types alongside Mermaid:

  • **```dot** — Graphviz DOT, with ```graphviz as an alias. Clusters (subgraph cluster_*), node shapes (box, ellipse, circle, doublecircle, diamond, hexagon, cylinder, trapezoid, …), fillcolor/color/fontcolor, style=filled,rounded, edge labels and solid/dashed/dotted/bold edges, rankdir, and the graph label all render. Colour is durable print too — every diagram is vector, so it stays sharp at any zoom.
  • **```graph** — a declarative YAML block for graphs your data shapes: nodes, groups (nestable, drawn as boundaries) and edges, with layout: layered | tree, direction: down | up | left | right, per-node shape/color, and edge label/style/arrow. JSON bodies work too — YAML is a superset. Unknown keys and dangling references are rejected with a message, so typos surface immediately.

Two presentational options are shared by both: an alt description (used as the figure's accessible alt text in tagged PDFs, so screen readers announce what the diagram shows) and a width percentage relative to the page content width, e.g. width: 60%. In a DOT block, put them in a --- front-matter header at the top of the block; in a ```graph block they are just top-level keys.

Nothing is dropped silently. DOT attributes this pipeline cannot honour — node style=dashed, hard-coded pos, rank=same constraints, unknown shapes — are drawn as well as they can be and reported in a single graph-unsupported-attributes warning naming each one. A block that cannot be rendered at all (a DOT syntax error, a dangling edge in a ```graph block, a broken Mermaid block) does not fail the document: it is shown as its source in a code block, with a diagram-render-failed warning carrying the parse error. Both warnings are returned in layoutWarnings on Accept: application/json responses.

POST /api/v1/md/validate reports the same parse errors before you render, as graph-invalid, and warns with graph-missing-description when a graph block carries no alt, so you can catch broken and undocumented diagrams in pre-render linting alongside mermaid-missing-description.