vitrine

docs: document the ```dot diagram syntax in the README

commit 9dcbf03d51823899671d22f76c8f690c95843271 · parent 0d2c580698 · browse this tree
Ximianth, 2026-08-09 14:08:12 UTC

Describes the dot/graphviz fenced-block syntax, the no-JS server-side SVG
rendering, and the fail-visible fallback, with a tiny example.

diff --git a/README.md b/README.md
index c0317c0..37f1a91 100644
--- a/README.md
+++ b/README.md
@@ -93,6 +93,28 @@ Callouts do not nest, by design,
 and an unterminated callout simply runs to the end of the document rather than breaking it.
 
 
+Diagrams
+--------
+
+A fenced code block tagged `dot` (or its alias `graphviz`)
+renders server-side to inline SVG, so diagrams need no JavaScript in the page.
+Write the DOT source in a normal fenced block:
+
+````
+```dot
+digraph { rankdir=LR; a -> b -> c; b [shape=box]; }
+```
+````
+
+- The source language is Graphviz's DOT.
+  Rendering runs entirely in-process via an embedded Graphviz WebAssembly build,
+  so there is no external `dot` binary to install and no browser involved.
+- A diagram whose DOT fails to compile does not break the page:
+  it falls back to showing its own source in a code block, flagged with the parse error,
+  so the author sees exactly what did not render.
+- Any other code language (or none) renders as an ordinary code block, unchanged.
+
+
 expose-git
 ----------