Reference · not a construct

Diagrams

A diagram is a fenced code block whose info string names a diagram language. There is no :::diagram directive and there will not be one, because a code fence already gives independent renderers everything they need to agree on. What this page describes is the part that did need settling: what a renderer is allowed to do with such a fence, and what it must never do.

Spec §10 No new syntax Works in plain CommonMark

The short version

Write the fence, wrap it in a figure

That figure is not an image file and not hand-written HTML. It is this, in the page source:

:::figure[How a request reaches a handler.]{#fig-flow}
```ascii
  +---------+      +----------+      +---------+
  | Ingress |----->|  Router  |----->| Handler |
  +---------+      +----------+      +---------+
                        |
                        |  no match
                        v
                   +-----------+
                   |  404 page |
                   +-----------+
```
:::

Both halves already existed. A fenced code block is CommonMark, and figure has always accepted a code block as its content. Nothing about the grammar changed to make this work.

Why ASCII

The fallback is already a diagram

This is the part that is about Markset rather than about diagrams, and it is the reason ASCII is the recommended source.

Every construct in Markset has to read where the layout cannot follow — a GitHub comment, a terminal, a plain-text mail, a diff, the output of markset downgrade. That is the degradation contract, and it is what the whole format is arranged around.

Both are on this page below, and both are drawn — this site registers an engine for each. So the difference is not in the picture, and the pictures are not the point. The difference is the second block in each column: what is left of that diagram somewhere the drawing cannot happen.

And in a pull request, a terminal, a plain-text mail:

flowchart LR
  Ingress --> Router
  Router --> Handler

And in a pull request, a terminal, a plain-text mail:

+---------+    +--------+    +---------+
| Ingress |--->| Router |--->| Handler |
+---------+    +--------+    +---------+

The bottom left is a set of instructions for a picture. The bottom right is a picture. Of the common diagram sources ASCII is the only one whose unrendered form is as good as its rendered form, which is what makes it the one that fits the degradation contract rather than merely surviving it. Renderers may draw anything they like; authors who care about where their document ends up should reach for ASCII first.

What a renderer may do

Seven obligations

Obligation 1 is the one that keeps the language set open. There is no list of approved diagram languages, and markset check reports nothing for a language it has never heard of, because a renderer that cannot draw one is already behaving correctly by leaving it alone.

Obligation 7

A drawn diagram must be captioned

The rule with teeth, and the one most likely to surprise. A diagram fence that is not the content of a captioned figure is rendered as a code block, however capable the renderer is.

The reason is worth spelling out. An undrawn diagram is a code block, so a reader using a screen reader gets its source: mediocre, but present. Draw it with no text alternative and that reader gets nothing at all — so drawing would remove content for them while adding it for everyone else. The caption is the alternative, and figure is the only place in the grammar a fence can carry one.

This is the same move as the tabs page's refusal to emit tab roles: the output claims only what it can keep true.

Drawing them

Rendering with the command line

ascii fences are drawn by default. The reference implementation ships one engine and uses it without being asked, because an ASCII fence that is drawn and an ASCII fence that is not are the same picture — drawing it changes how it looks, not what it says. Every other language needs a command, and --diagram none turns drawing off entirely for a fence that is meant to stay selectable text.

markset html doc.md -o doc.html      # ascii fences are drawn
markset html doc.md --diagram none   # and this keeps them as code

markset html doc.md --diagram mermaid="mmdc -i /dev/stdin -o /dev/stdout"
markset html doc.md --diagram bob="svgbob"

import { renderHtml } from "@markset-lang/render-html";

renderHtml(ast);                                        // ascii is drawn
renderHtml(ast, { diagrams: false });                   // nothing is drawn
renderHtml(ast, { diagrams: { engines: { mermaid } } }); // ascii and mermaid

What gets emitted

The drawn form

A drawn diagram replaces the <pre> with an image:

<img class="ms-diagram" data-diagram="ascii" src="data:image/svg+xml,…" alt="How a request reaches a handler.">

The reference implementation draws to SVG and embeds it as a data: URI rather than inlining the markup. Markset never passes raw HTML from a document through to output, and an engine — which on the command line is an arbitrary command — should not get a channel that documents are denied. An SVG loaded through <img> cannot execute script, so obligation 6 holds because of the shape of the output rather than because the engine was trusted.

The built-in engine carries its own prefers-color-scheme block, which resolves against the page's color scheme, so a diagram follows the light and dark control in the bar above like everything else on the page. Try it: the picture at the top of this page changes with it.

The supported subset

What the built-in engine understands

The last two rows are the ones that matter in practice. An arrowhead is only an arrowhead where a line arrives at it, which is what stops the v in "very" from sprouting a triangle. And there is no layout pass: a diagram is drawn exactly where you put it, cell by cell, so the alignment in the rendered picture is the alignment in your file.

The engine is deliberately small and deliberately not svgbob. If you want rounded corners, shape detection and styling hints, point --diagram at a tool that does those things — that is what the flag is for.