Diagrams

flowcharts and other drawings, written as text

A diagram is a code block whose language is mermaid, and the site draws it as a picture instead of showing its text.^[1] Mermaid is the diagram language GitHub draws from the same block, so one page reads as a diagram on GitHub and on the wiki.^[2] How a page is written in general is described on Pages.

Writing

A diagram is written between fences that name its language as mermaid.^[1]

Every push checks the wiki before it is published.[^flow]

```mermaid
flowchart LR
  accTitle: Checking before publishing
  accDescr: A push checks the wiki; a problem stops it with nothing published, otherwise the site is published.
  pushed(["Push to main"]) --> check["Check the wiki"] --> passed{"Check passed?"}
  passed -- "Yes" --> publish["Publish the site"] --> published(["Site published"])
  passed -- "No" --> stopped(["Nothing published"])
```

Only a page with a mermaid block loads Mermaid, and its block is drawn in three steps.^[1][3]

flowchart LR
  accTitle: Diagram drawing
  accDescr: When a page is built, a page without a mermaid block is shown without Mermaid. A page with one has the block marked as a diagram, loads Mermaid, and has the diagram drawn in its theme.
  built(["Page built"]) --> has{"Mermaid block<br/>on the page?"}
  has -- "Yes" --> mark["Mark it as a diagram"] --> load["Load Mermaid on the page"]
  load --> draw["Draw it in the page's theme"] --> shown(["Diagram shown"])
  has -- "No" --> plain(["Page shown without Mermaid"])

Drawing

A diagram needs no network: Mermaid ships inside wiki-builder, and a build copies it, with its licence, into a site only when some page has a diagram.^[3] Only a page with a diagram loads it.^[3] A diagram is drawn in the page's theme, light or dark, and is drawn again whenever the theme changes, whether the reader switches it or the system does.^[4] It sits centred without a frame, and scrolls sideways inside itself when it is wider than the page.^[5]

Citations

A diagram states what something does, so the sentence introducing it carries the citation, and every box and arrow must be something the cited code does.^[6] The check does not read inside a code block, so a diagram is never refused for citing nothing.^[7] It costs nothing against the page's reading budget.^[8]

Copies

A page's markdown copy keeps a diagram as the block it was written as, which is how an agent reads it.^[9] The copies are described on Agent markdown, and wiki-builder's own diagrams are on Checks, Citations and Deployment (GitHub).