org-special-block-extras: Org lists, drawn as Graphviz graphs

org-graph-block extends org-special-block-extras:

(require 'org-special-block-extras)
(require 'org-graph-block)

Graphviz must be on our PATH: dot -V should work in a terminal.

The fun part is how quickly a picture grows. Start with the seven tokens as a flat list, one item each, and press C-c C-c anywhere in the block: seven lonely nodes. Now M-S-<right> demotes an item, children and all —Org's own list editing— and another C-c C-c shows the new arc. A minute later, the flat list is the tree above. (Plain M-<right> demotes the item alone, leaving its children behind, as anywhere in Org.)

C-c C-c renders a PNG and links it beneath the block, under #+RESULTS:. The file's name is made up, unless :file picks one:

#+begin_graph :file parse-tree.png
…
#+end_graph

When the picture surprises us, C-u C-c C-c shows the generated dot instead; see Comforts while editing.

An inline link is quick, but its arc has nowhere to keep a style of its own. So the arc graduates to a child item that is nothing but a link: a reference to its target. Nesting makes the arc, and a description term labels it, exactly as for any other child:

+ <<lam>> λ-calculus
+ Fortran
+ Lisp
  + borrows :: lam
  + Fortran

Lisp -> lam [ label=borrows ];
Lisp -> Fortran;

• A reference never declares its target: the target's own item names and labels it, even when that item comes later. Node attributes on a reference are an error; they belong on the target's item.
• + [[church][encodes]] is a reference too, its arc labelled encodes.
• Two references to one target are two parallel arcs, each styled on its own.
• A reference may name a record's port, [[struct1::mid]], or a cluster; both are met below.

When one node is mentioned everywhere, bracketing each mention is a chore. In Org, a radio target <<<Church>>> stays visible, and every mention of “Church” elsewhere becomes a link to it, sans brackets. In a graph, the radio target is a node, and every item mentioning it —in whatever case— has an arc to it:

+ <<<Church>>> encodes numbers as Church numerals
+ Lisp, after Church
+ Haskell, after church and Lisp

Church [ label="Church encodes numbers as Church numerals" ];
"Lisp, after Church" -> Church;
"Haskell, after church and Lisp" -> Church;

The mention stays in the label, and the radio target's own item never arcs to itself. Mind that this is Org's semantics exactly: a casual “Church” draws an arc too.

By way of example, this item has one row of each kind:

+ Alonzo
  | label | Alonzo Church |
  | :id   | church        |

church [ label="Alonzo Church" ];

A plain key, such as label, is a Graphviz attribute of the node, passed straight through. We quote its value for you, so Alonzo Church, #00ff00, and x -> y all need no quotes; already-quoted values, and <…> HTML labels, are left alone.

A key starting with a colon is reserved: it means something to the graph block itself, never to Graphviz. A leading colon is never a Graphviz attribute, so the two kinds cannot clash. The reserved keys are listed in org-graph-reserved-keys; each is met in due time:

An unknown :key is an error, rather than a silently ignored attribute.

An arc is drawn from parent to child, so the child's table is where it is styled: an :edge.KEY row there is attribute KEY of the arc into the item. Every attribute is its own row, exactly like a node's. Our client's two arcs to one server now look different:

+ client
  + request :: server
    | :edge.color | blue |
  + retry :: server
    | :edge.style | dashed |

client -> server [ label=request color=blue ];
client -> server [ label=retry style=dashed ];

A reference is styled just the same; this is why an inline link graduates to one:

+ Lisp
  + borrows :: lam
    | :edge.style | dotted |

Lisp -> lam [ label=borrows style=dotted ];

• A parallel arc is simply a second child, styled on its own; a KEY given twice is an error.
• As in Org, an item's tables and directives may also follow its sub-items; they still belong to it.

Small graphs deserve no preamble at all. So the header line takes the graph's title and any graph attribute:

#+begin_graph Lambda calculus :rankdir LR :node.shape box :edge.color grey
+ λ
  + Lisp
#+end_graph

graph [ label="Lambda calculus" rankdir=LR ]
node [ shape=box ]
edge [ color=grey ]

• The title, the words before the first :key, is the graph's label; :directed nil makes the graph undirected, with -- arcs.
• :KEY V is a graph attribute; :node.KEY V and :edge.KEY V are node and edge defaults —the same KEY, node.KEY, edge.KEY spelling as table rows.
• As on Org's own #+attr_html: lines, values need no quotes: :bgcolor #6c7086, :fontname Helvetica,Arial. A value with spaces does: :fontname "Helvetica Neue".
• :file, :svg, :directed, :wrap, :notes, :unflatten, :unknown-tags, :smartdiagram, :dpi, and :C-c_C-c belong to the block itself, never to Graphviz; each is met below. So do the Babel habits :exports and :results, which the block ignores.

A real graph's settings outgrow one line. Then #+graph:, #+node:, and #+edge: name what the table below them styles —the graph, every node, every arc— and they override the header. A drawer of any name, :SETTINGS: or :PALETTE:, folds them away with TAB, along with #+rank: and #+name: lines:

#+begin_graph Lambda calculus
:SETTINGS:
#+graph:
| rankdir | LR |
#+node:
| shape | box |
:END:
+ λ
  + Lisp
#+end_graph

graph [ label="Lambda calculus" rankdir=LR ]
node [ shape=box ]

Sometimes a style belongs to one branch, not the whole graph. Org's properties are inherited: a :PROPERTIES: drawer on a heading reaches its subheadings. So it is with an item's #+node: and #+edge: tables: they style every node and arc beneath the item, while the item itself keeps its own | key | value | rows; its #+rank: lines apply there too. Graphviz scopes such defaults by an anonymous subgraph, which draws no box:

+ Weather
  #+node:
  | shape | box |
  #+edge:
  | style | dotted |
  + Rain
    + Umbrella
  + Sun
+ Climate

Weather [ label=Weather ];
subgraph {
  node [ shape=box ]
  edge [ style=dotted ]
  Weather -> Rain;
  Rain [ label=Rain ];
  Rain -> Umbrella;
  Umbrella [ label=Umbrella ];
  Weather -> Sun;
  Sun [ label=Sun ];
}
Climate [ label=Climate ];

A deeper item's tables override a shallower one's, as nested :PROPERTIES: do; a node first declared elsewhere keeps the defaults of where it was declared.

Each tag is terse sugar for an :inherit row, which names one or more templates and is often the clearer choice in a long-lived graph: | :inherit | wife | in an item's table or under #+node:, | :edge.:inherit | married | for the arc into an item. Wherever it sits, the item's explicit rows still win.

• A template may inherit others; one that, directly or not, inherits itself contributes nothing the second time.
• A name that no #+name: defines is an error, rather than a silent nothing.
• As with Babel's named tables, a #+name: table anywhere in the buffer, outside any graph, is a template every graph in the buffer may use; so a house style ---wife, married— is named once per file rather than once per graph. A graph's own template of the same name wins, and a template inside one graph stays that graph's own.

Tags are trailing :word: groups, exactly as on a headline; inside graph blocks, they wear Org's org-tag face, so they do not read as part of the label. Colons anywhere else are just text, and a label that needs a trailing :word: of its own puts it in =verbatim=, or in a | label | row:

+ Ratio 1:2
+ std::vector
+ Meeting at 12:30 :faint:
+ Vim's =:wq:=

"Ratio 1:2" [ label="Ratio 1:2" ];
"std::vector" [ label="std::vector" ];
"Meeting at 12:30" [ style=dotted label="Meeting at 12:30" ];
"Vim's :wq:" [ label=<Vim's <FONT FACE="monospace">:wq:</FONT>> ];

Unlike Org's, our tags may be kebab-case: :killed-by:. A tag naming no template is an error, rather than a typo silently becoming part of the label.

That strictness is right for a finished graph, and in the way of a sketch: while prototyping, we want shapes before names. #+begin_graph :unknown-tags random-templates makes up a template for each unknown tag —a colour, a shape, a font— the same at every use, so the tags read at a glance. A legend entry gives each its meaning; when the design settles, #+name: tables replace the made-up templates, one tag at a time:

The Nth unknown tag takes the Nth of org-graph-random-template-colours, -shapes, and -fonts, so renders are stable, and the first eight tags differ in every way.

A reader meeting pink arcs asks what pink means. A legend answers: a glossary of templates. Org's glossary is the description list, so a top-level - :T: :: MEANING —which has no parent to arc from— is a legend entry: a sample styled by template T, captioned MEANING. Wrap the entries in a #+begin_cluster to box them:

#+name: married
| color | pink |
| dir   | both |
#+name: wife
| shape | box |

+ Muhammad
+ Khadija :wife:
  + Muhammad :married:
#+begin_cluster Legend
- :married: :: marriage
- :wife: :: /wife/
#+end_cluster

subgraph cluster_Legend {
  label=Legend
  legend_1 [ shape=point style=invis ];
  legend_1_end [ shape=point style=invis ];
  legend_1 -> legend_1_end [ color=pink dir=both label=marriage ];
  legend_2 [ shape=box label=<<I>wife</I>> ];
}

• The legend can never drift from the graph: change married, and its sample changes too.
• A template that styles some arc in the graph —by a reference's or a term's tags, an :edge.:inherit row, or an #+edge: line— is sampled as an arc; any other, as a node.
• …~, sample their templates together.
• The sample drops constraint, which shapes the layout rather than the arc.

A checkbox says how far along a thing is; so a graph of tasks is just a checklist. [X], [-], and [ ] apply the templates checked, partial, and unchecked, as a :checked: tag would; and C-c C-c on a checkbox toggles it, as Org's own does, then renders the graph:

#+name: unchecked
| style | dashed |

+ [-] compile
  + [X] parse
  + [ ] typecheck

compile [ color=darkorange fontcolor=darkorange label=compile ];
parse [ color=forestgreen fontcolor=forestgreen label=parse ];
typecheck [ style=dashed label=typecheck ];

checked and partial default to green and orange, by org-graph-checkbox-templates; a graph's own #+name: template wins. A checkbox whose template exists nowhere, such as unchecked by default, styles nothing.

Templates name whole bundles of rows; sometimes we want to name one value. A palette repeats itself, and Org's #+macro: names a value once, so {{{name}}} uses it —in a table, an item, a cluster's header, anywhere in the block:

#+macro: gold #f9e2af
#+begin_graph
+ Church
  + Turing
    | :edge.color     | {{{gold}}} |
    | :edge.fontcolor | {{{gold}}} |
#+end_graph

An undefined macro is an error. In similar spirit, inline src_LANG{…} blocks and call_NAME() calls run at export, as anywhere in Org, their results landing in the label; C-c C-c shows them as written.

*bold*, /italic/, _underline_, +strike+, =code=, and ~pre~ in an item's text make its label an HTML-like one, while its id stays the plain text:

+ *Church* encodes =Bool=

"Church encodes Bool" [ label=<<B>Church</B> encodes <FONT FACE="monospace">Bool</FONT>> ];

We escape &, <, >, and " for you. Graphviz has no way to tell =code= from ~pre~, so both are monospace. A #+record: table's cells keep their markup too. Names such as a_b, C++, and org-graph.el are not mistaken for markup.

Org's entities are their characters, and braced sub- and superscripts are Graphviz's own; as under Org's #+options: ^:{}, an unbraced a_b stays text, so snake_case ids are safe. For whatever Org has no markup for, a @@dot:…@@ export snippet is raw label HTML; a snippet for any other backend vanishes:

+ \alpha \to \beta
+ x^{2} H_{2}O
+ @@dot:<FONT COLOR="red">@@Alert@@dot:</FONT>@@

"α → β" [ label="α → β" ];
"x2 H2O" [ label=<x<SUP>2</SUP> H<SUB>2</SUB>O> ];
Alert [ label=<<FONT COLOR="red">Alert</FONT>> ];

• Timestamps, statistics cookies, and citations show as written; LaTeX fragments too, since Graphviz has no math.
• Syntax that means nothing in a graph —a headline, a #+begin_quote, an unknown #+key:— is an error, rather than silently dropped. Comments, and footnote definitions, are fine.

A long label makes a wide node, and a wide node a sprawling graph. In Org, a \\ ending a line is a hard line break; in a graph, it breaks the node's label. Since a label seldom wants a literal \\, it may sit mid-line too, so a two-line node stays one terse line:

+ Emacs
  + provides :: <<closures>> Closures \\ (lexical scope)
  + *Lisp* \\
    McCarthy, 1958

Emacs -> closures [ label=provides ];
closures [ label=<Closures<BR/>(lexical scope)> ];
Emacs -> "Lisp McCarthy, 1958";
"Lisp McCarthy, 1958" [ label=<<B>Lisp</B><BR/>McCarthy, 1958> ];

The label becomes an HTML-like one, as with markup; the id joins the lines with a space, so a node reached by a link usually wants a <<target>>, as closures above.

It is the one line break wherever a label is written: a description term, a table value, a #+record: cell. So an arc's label breaks just as its node's does:

+ Monad
  + every monad \\ is an adjunction :: Adjunction
  + Turing
    | :edge.label | Church– \\ Turing thesis |

Monad -> Adjunction [ label=<every monad<BR/>is an adjunction> ];
Monad -> Turing [ label="Church–\nTuring thesis" ];

Breaking every long label by hand is tedious, though. #+begin_graph :wrap N fills node and arc labels to lines of N characters, so long item text needs no \\ at all; a label already broken by \\ stays as written.

A footnote is an aside we read when we want it; so is a tooltip. An inline footnote leaves the label and becomes the node's tooltip —shown on hover in an :svg t HTML export, and in Emacs too:

+ Lisp [fn::McCarthy, 1958]

Lisp [ tooltip="McCarthy, 1958" label=Lisp ];

A named footnote serves too: [fn:NAME: NOTE] inline, or a bare [fn:NAME] whose [fn:NAME] NOTE definition sits elsewhere in the buffer —say, below the graph. An explicit | tooltip | … | row wins.

A footnote is awkward for more than a line. An item's text is its first paragraph, as in Org; every paragraph after it is a note, the tooltip of whatever its item's line describes: a node, or —under a reference— an arc. #+begin_note :edge, sitting in an item as a #+begin_cluster may, describes the arc into the item instead; it is the one place we need the block:

+ Lisp [fn::1958]

  McCarthy's /list processor/:
  code is data.
  + Scheme
    #+begin_note :edge
    Steele and Sussman distilled it.
    #+end_note

Lisp [ tooltip="1958\nMcCarthy's list processor: code is data." label=Lisp ];
Lisp -> Scheme [ tooltip="Steele and Sussman distilled it." ];

The blank line matters: without it, McCarthy's list processor: continues the first paragraph, and so the label. Likewise + <<lisp>> Lisp, the list processor names its node lisp and labels it with the whole line; a <<target>> names, but only a new paragraph begins a note.

Tooltips need a hover, and a PNG pasted into an email has none. #+begin_graph :notes inline shows every note beneath its label instead, in a smaller font, its markup kept and its lines filled to :wrap —else 40— characters:

• A note's lines join, and each paragraph —or \\ break— starts a new line.
• A note follows the item's footnotes, which stay tooltips; an explicit tooltip, :edge.tooltip, or label row wins.
• A note outside every item is the graph's: its tooltip, or —inline— the text beneath its title. One directly in a #+begin_cluster is the box's.
• Within a graph, #+begin_note is never the callout of the same name, and C-c C-c in it renders the graph.

A link to anything but a node keeps its Org meaning. A web or file link makes the node clickable in an :svg t HTML export, its description staying in the label; a description-less link to an image draws that image:

+ Org mode
+ <<emacs>> Emacs file:emacs.png
+ file:gnu.png

"Org mode" [ URL="https://orgmode.org" label="Org mode" ];
emacs [ image="emacs.png" label=Emacs ];
"gnu.png" [ image="gnu.png" label="" ];

A node has one URL, so an item with two web links is an error. Graphviz finds the image relative to the Org file, as Org does; an explicit URL or image row wins.

So a graph of screenshots is a tour. A lone image is its own node, drawn sans text, so the arc into it carries the words; imagescale fits each picture to its node's fixed size:

A link to a section, [[*Heading]], is a URL too —not an arc, since nodes are named without a star. In an :svg t HTML export it leads to that section's anchor, which only Org knows; and in Emacs, a click on the rendered node opens the section. So a graph may be a map of its own document:

#+begin_graph This section :svg t :rankdir LR
+ [[*Asides: footnotes, notes, and links][Asides]]
  + [[*Footnotes are tooltips][Footnotes]]
  + [[*Notes are longer tooltips][Notes]]
#+end_graph

A bare [[*Footnotes are tooltips]] labels its node with the heading's title; [[#custom-id]] and [[id:…]] links work alike.

Look again at our parse tree: 1 * 2 + 3 - 4 subtracts 4 from the rest, never the other way around, yet nothing in an unordered list promises Graphviz will draw 4 on the right. Org's + - * bullets say “these things”; 1. 2. 3. say “first, second, third”. So ordered children sit side by side, on one rank, in the order written —Graphviz no longer reshuffles them to save a crossing:

+ -
  1. +
     1. *
        1. 1
        2. 2
     2. 3
  2. 4

"-" [ ordering=out label="-" ];
"-" -> "+";
"-" -> 4;
{ rank=same; "+"; 4 }
…

• An ordered top-level list, or one inside a cluster, shares a rank too.
• An explicit | :children-rank | min | wins over the rank=same; a lone ordered child gets no rank at all.
• For one rank without the fixed order, use | :children-rank | same | with + bullets.

Nodes with no common parent share a rank by #+rank:, which takes bare ids or links; a link spares a multi-word id its quotes:

+ Logic
  + λ calculus
+ Lisp
#+rank: Lisp [[λ calculus]]

{ rank=same; "λ calculus"; Lisp }

Under splines=curved, Graphviz drops the label of an arc between two nodes on one rank; so there, such an arc's label becomes an xlabel, which it still draws.

Some nodes belong together —Emacs's packages, say— and a box around them says so. A cluster is a subgraph, so it gets the graph's own spelling: a #+begin_cluster block takes a title and :KEY V attributes, :node.KEY and :edge.KEY defaults included, exactly as the #+begin_graph line does; and, being a block, it folds with TAB:

+ Emacs
  #+begin_cluster Packages :bgcolor lightgrey :node.shape box
  + Org
    #+begin_cluster
    + agenda
    + babel
    #+end_cluster
  + Magit
  #+end_cluster

graph [ compound=true ]
subgraph cluster_Packages {
  label=Packages
  bgcolor=lightgrey
  node [ shape=box ]
  Org [ label=Org ];
  subgraph cluster_anonymous_1 { label="" agenda; babel; }
  Org -> agenda [ lhead=cluster_anonymous_1 ];
  Magit [ label=Magit ];
}
Emacs -> Org [ lhead=cluster_Packages ];

• A cluster block inside an item is that item's child: above, Emacs has an arc to Packages. An arc to or from a cluster lands on the cluster's first node, clipped at its border, as lhead shows.
• An untitled cluster is an anonymous box, with no label and no name to draw arcs to.
• The title runs up to the first :KEY; #+begin_cluster Time 12:30 is titled Time 12:30.

• When the attributes outgrow the line, a table opening the block styles the box, as an item's table styles its node; #+node: and #+edge: tables set defaults inside it, as usual:

  #+begin_cluster Prophets
  | style     | filled  |
  | fillcolor | #ddeeff |
  #+node:
  | fillcolor | #aaccff |
  + Adam
  #+end_cluster
  

• C-c C-c, C-M-i, and eldoc work inside a cluster block just as anywhere else in the graph.

Some nodes have insides: a C struct has fields, a UML class has members, and an arc may want to leave from one particular field. A record is a node drawn as a table, and Org already has tables: under #+record:, an item's table is its label, laid out exactly as written —just as #+graph:, #+node:, and #+edge: name what the table below them is. A cell's <<target>> is its port, a cell's [[link]] is an arc from that port, and an arc reaches a port by record::port —just as Org's [[file:notes.org::target]] reaches into a file:

+ struct1
  #+record:
  | left | <<mid>> middle struct2::one | right |
+ struct2
  #+record:
  | <<one>> one | two   |
  | ^           | three |
+ reader
  + struct1::mid

struct1 [ shape=plain label=<<TABLE …><TR><TD>left</TD><TD PORT="mid">middle</TD><TD>right</TD></TR></TABLE>> ];
struct1:mid -> struct2:one;
struct2 [ shape=plain label=<<TABLE …><TR><TD PORT="one" ROWSPAN="2">one</TD><TD>two</TD></TR><TR><TD>three</TD></TR></TABLE>> ];
reader -> struct1:mid;

Org tables have no merged cells, so two markers stand in for them: ^ continues the cell above, as one does, and an empty cell continues the cell to its left —or, in the first column, the one above. Together they draw any layout that Graphviz's old { } nesting could:

+ struct3
  #+record:
  | hello \\ world | b |            |   | g | h |
  | ^              | c | <<here>> d | e | ^ | ^ |
  | ^              | f |            |   | ^ | ^ |

Here b and f span three columns, hello, g, and h three rows; a \\ breaks a line, as in an item. The gallery has both records live.

Hlines and column cookies mean what they mean to Org. An hline draws a rule between rows, and a table with any hline draws one outer border rather than a box around every cell —so a UML class is just the table we would write anyway. A row of <l>, <c>, and <r> cookies aligns its columns, and cells keep their markup:

+ Person
  #+record:
  | <l>            |
  | *Person*       |
  |----------------|
  | name: =String= |
  | age: =Int=     |
  |----------------|
  | greet()        |

Person [ shape=plain label=<<TABLE BORDER="1" CELLBORDER="0" CELLSPACING="0"><TR><TD ALIGN="LEFT" BALIGN="LEFT"><B>Person</B></TD></TR><HR/>…</TABLE>> ];

• A record is otherwise an ordinary node: its children are nodes of their own, and its attributes, tags, and templates apply as usual; color, fillcolor, and fontcolor colour the table. Its attribute table goes above #+record:, since rows right below the record table are part of it.
• A record is shape=plain, the table being its whole outline; an explicit shape row wins.
• A cell with a link but no target is ported by its text, spaces as underscores; <<x marks the spot>> is likewise reached as [[struct3::x marks the spot]].
• Ports belong to their record, so two records may both have a head port: r1::head and r2::head.
• A cell's trailing tags style its arcs, as a reference's style its arc: | <<mid>> middle [[struct2::one]] :dashed: | draws a dashed arc. A cell with tags but no link is an error; write =:x:= for literal text.
• a::b names a port only when a names a record; otherwise it is an ordinary node, such as std::vector. Record and port names may contain dots: [[org.el::v1.2]].
• Graphviz spells ports record:port; that is the spelling in the generated dot.

Every graph so far flows top to bottom; a mind map grows outward from its centre. Graphviz's layout attribute picks its engine, so the header line turns a tree into a mind map: twopi places root in the middle and each generation on a ring around it. With :wrap, long labels stay compact:

Sans :root, twopi picks a centre itself. neato, fdp, and circo suit graphs that are not trees.

A node with many children lays them out in one wide row: a ribbon, too wide for the page. :unflatten N passes the dot through Graphviz's own unflatten -l N, which staggers those leaves over N ranks, so the graph is a block rather than a ribbon:

We want to write “as Figure 1 shows”, and have the number stay right. In Org, #+name: is what [[links]] reach, and #+caption: captions a table or an image. A graph is an image, so both mean what they always do:

As lineage shows, Emacs is a Lisp.

#+name: lineage
#+caption: How Emacs came to be
#+begin_graph
+ λ-calculus
  + Lisp
    + Emacs Lisp
#+end_graph

• The graph renders to lineage.png —both on C-c C-c and on export— and exports as that image, numbered and captioned: [[lineage]] reads “Figure 1” in HTML, and \ref in LaTeX.
• An explicit :file still wins: #+begin_graph :file elsewhere.png renders there, and the #+name: still labels it. With :svg t, the figure is lineage.svg.
• An unnamed graph exports as before: inlined into HTML, or as dot source elsewhere.

Sometimes a whole section is nothing but the outline we want drawn; wrapping it in a block is ceremony. A #+begin_graph block is a function on a region; a :graph: tag is the same function on a section. The section's text is the graph, and its :PROPERTIES: drawer —Org's own home for key-value settings— is the #+begin_graph line: :RANKDIR: LR is :rankdir LR, :NODE.SHAPE: box is :node.shape box, and :FILE: is :file. See the live example:

* Emacs's lineage :graph:
:PROPERTIES:
:RANKDIR: LR
:NODE.SHAPE: box
:END:
+ λ-calculus
  + inspired :: Lisp
    + Emacs Lisp

• The heading stays a heading; only its text becomes the graph, on export.
• :graph_Some_Title: titles the graph Some Title, as the words before the first :key would.
• Org's own properties, such as :CUSTOM_ID: and :CATEGORY:, stay Org's; they never reach Graphviz.

Why bother, when LaTeX could draw it directly? The diagram above began life as a #+begin_src latex-as-png block, via ob-latex-as-png. Every LaTeX incantation it needed has an Org counterpart that we already write daily:

The LaTeX column is a second language inside our Org file: its macros, its colour syntax, and hand-tuned \hspace's that drift the moment a line changes. The Org column is the language the rest of the file is already in; it folds, links, exports, and completes like everything around it. The only backslashes that survive the move are \\ —which Org itself reads as a line break— and the font names, such as \small, that smartdiagram's own settings take as values.

Some of us prefer every attribute in a key-value table, never in the list's shape. Two spellings serve that taste; the examples above avoid them, but they are fully supported.

An inline link's arc is styled by :edge[T].KEY, naming the arc by where it goes; :edge[T].:inherit applies a template to it. A row with no [[T]] link in the item's text is an error:

+ <<lam>> λ-calculus
+ Lisp borrows
  | :edge[lam].style | dotted |

Lisp -> lam [ label=borrows style=dotted ];

A | shape | cluster | row makes an item a cluster, as #+begin_cluster does. Its children are then its members rather than arc targets, so arcs out of them are inline links, styled as above:

+ Emacs
  + Packages
    | shape | cluster |
    + Org
    + Magit

graph [ compound=true ]
subgraph cluster_Packages { label=Packages Org; Magit; }
Emacs -> Org [ lhead=cluster_Packages ];

A decision tree is a tree whose nodes come in kinds: decisions we make (boxes), chances we take (circles), and outcomes (bare text), with each chance's arcs labelled by how likely it is. Templates name the kinds, description terms label the arcs, and an item's #+edge: dashes every arc of chance beneath it:

The chance node is all target: <<specials>> names it, and its template's empty label leaves a dot.

A chapter of Sönke Ahrens' How to Take Smart Notes, as we would outline it while reading. Each connective, such as “is an aid for”, sits on its arc, as a description term; ordered steps are numbered arcs; :smart_kind: —a template named outside the graph— marks the three kinds of note; and [[fleeting]] arcs back to a note met earlier:

An item's #+record: table is its label, drawn as laid out; <<mid>> makes The Middle a port, whose link is an arc from it:

Spans replace { } nesting: ^ continues the cell above, and an empty cell the one to its left. A multi-word port is reached by its words, and a reference's :edge.KEY rows style the arc into it:

Next comes a section whose whole text is a graph, by its :graph_Lineage: tag; so it has no prose of its own, lest the prose become part of the graph.

Now everything at once: a header drawer's worth of #+graph:, #+node:, and #+edge: tables; #+rank: lines; arc templates by tags, sampled in a legend; clusters; and labels broken by \\. Its palette is Catppuccin's; the colours it repeats are named once, by Org's own macros:

The graph above, as it was first written, before templates and legends existed: every arc styled by its own :edge.KEY rows, every colour spelled out, its settings folded in a :SETTINGS: drawer, and a legend of plain-text nodes. Comparing the two is demonstrative of what each feature saves.

A genealogy of the prophetic lineage (Adam → Noah → Ibrahim → … → Muhammad ﷺ) and the family of Imam Hussain ibn Ali at Karbala: his wives, his children, the antagonists (Muawiya, Yazid, Ibn Ziyad, Shimr), and a legend. It is demonstrative of most of this README at once: a :SETTINGS: drawer, #+begin_cluster blocks with scoped #+node: overrides, #+rank: groupings, diamond shapes for key Karbala actors, \\ multi-line labels, footnote tooltips, and templates for the pink marriage arcs and red martyrdom arrows —all without a single line of raw dot.