examples

Diagrams that ship with the artifact

Write Mermaid. The built-in artoo-diagrams library renders it offline with Pele, in the page's own type and colors.

Each diagram below is a <pre class="mermaid"> block in this page's HTML, rendered in the browser by a vendored, hash-pinned copy of Pele. Nothing loads from a CDN, and with JavaScript off the source is still there to read. Use the theme button: the diagrams recolor without being redrawn, because Pele reads its colors from the kit's CSS tokens. On a narrow screen, wide flowcharts turn vertical, and diagrams that had to shrink can be zoomed.

artoo lib add artoo-diagrams   # Markdown content vendors it on its own
artoo docs artoo-diagrams      # the authoring contract

Flowchart: what `artoo build` does

The most common diagram: a process with gates in it. The gates are tagged :::accent, a role artoo-diagrams colors from the kit's tokens, so they recolor with the theme.

flowchart LR
  accTitle: What artoo build does
  accDescr: Build validates the manifest, refreshes inputs, renders content, then gates the site through the firewall and static verification before stamping the updated date.
  manifest[Validate artifact.toml] --> commands[Run build commands]
  commands --> data[Pack data]
  data --> content[Render Markdown content]
  content --> firewall{{Publish firewall}}:::accent
  firewall --> verify{{Static verification}}:::accent
  verify -->|ok| stamp[Stamp updated]
  verify -->|problems| fix[Report the fix]:::warn

The firewall and verification are gates: a problem at either stops the build and names the fix.

Mermaid source

flowchart LR
  accTitle: What artoo build does
  accDescr: Build validates the manifest, refreshes inputs, renders content, then gates the site through the firewall and static verification before stamping the updated date.
  manifest[Validate artifact.toml] --> commands[Run build commands]
  commands --> data[Pack data]
  data --> content[Render Markdown content]
  content --> firewall{{Publish firewall}}:::accent
  firewall --> verify{{Static verification}}:::accent
  verify -->|ok| stamp[Stamp updated]
  verify -->|problems| fix[Report the fix]:::warn

Sequence: a deploy to GitHub Pages

Who talks to whom, in order. Activation bars and notes are supported.

sequenceDiagram
  accTitle: Deploying an artifact to GitHub Pages
  accDescr: The author runs artoo deploy; artoo stages only publishable files, the deployer copies them into the Pages tree, and git records the change.
  actor Author
  participant artoo
  participant Firewall
  participant Pages as GitHub Pages deployer
  Author->>artoo: artoo deploy site/report
  artoo->>Firewall: stage(site/)
  Firewall-->>artoo: publishable files only
  Note right of Firewall: work/, notebooks, and _private paths never ship
  artoo->>Pages: copy staged site into docs/
  Pages-->>Author: committed (never pushed unless asked)

Deploys are deny-by-default: the deployer only ever sees what the firewall staged.

Mermaid source

sequenceDiagram
  accTitle: Deploying an artifact to GitHub Pages
  accDescr: The author runs artoo deploy; artoo stages only publishable files, the deployer copies them into the Pages tree, and git records the change.
  actor Author
  participant artoo
  participant Firewall
  participant Pages as GitHub Pages deployer
  Author->>artoo: artoo deploy site/report
  artoo->>Firewall: stage(site/)
  Firewall-->>artoo: publishable files only
  Note right of Firewall: work/, notebooks, and _private paths never ship
  artoo->>Pages: copy staged site into docs/
  Pages-->>Author: committed (never pushed unless asked)

State: a vendored library

Lifecycles and status machines. These are the states artoo lib status reports. This one is wide, so its figure adds article-breakout to leave the prose column.

stateDiagram-v2
  accTitle: States of a vendored site library
  accDescr: A library is intact after artoo lib add. Editing its files makes it modified, deleting them makes it missing, and a newer installed version makes it outdated. artoo lib update returns it to intact.
  [*] --> intact: artoo lib add
  intact --> modified: files edited
  intact --> missing: files deleted
  intact --> outdated: newer artoo installed
  modified --> intact: artoo lib update
  missing --> intact: artoo lib update
  outdated --> intact: artoo lib update

Vendored copies are hash-pinned; artoo lib update is the only way back to intact.

Mermaid source

stateDiagram-v2
  accTitle: States of a vendored site library
  accDescr: A library is intact after artoo lib add. Editing its files makes it modified, deleting them makes it missing, and a newer installed version makes it outdated. artoo lib update returns it to intact.
  [*] --> intact: artoo lib add
  intact --> modified: files edited
  intact --> missing: files deleted
  intact --> outdated: newer artoo installed
  modified --> intact: artoo lib update
  missing --> intact: artoo lib update
  outdated --> intact: artoo lib update

Entity relationship: what a manifest records

Schemas and data models, with typed attributes and cardinality.

erDiagram
  accTitle: What artifact.toml records
  accDescr: An artifact vendors zero or more libraries, packs zero or more data sources, and has at most one deploy target.
  ARTIFACT ||--o{ LIBRARY : vendors
  ARTIFACT ||--o{ DATA : packs
  ARTIFACT ||--o| DEPLOY : "publishes to"
  ARTIFACT {
    string slug
    string kind
    string form
    date updated
  }
  LIBRARY {
    string name
    string version
    string sha256
  }
  DATA {
    string source
    string output
  }
  DEPLOY {
    string target
  }

Every vendored library carries its version and a content hash.

Mermaid source

erDiagram
  accTitle: What artifact.toml records
  accDescr: An artifact vendors zero or more libraries, packs zero or more data sources, and has at most one deploy target.
  ARTIFACT ||--o{ LIBRARY : vendors
  ARTIFACT ||--o{ DATA : packs
  ARTIFACT ||--o| DEPLOY : "publishes to"
  ARTIFACT {
    string slug
    string kind
    string form
    date updated
  }
  LIBRARY {
    string name
    string version
    string sha256
  }
  DATA {
    string source
    string output
  }
  DEPLOY {
    string target
  }

Timeline: artoo releases

Dated sequences. Pele colors timeline sections from the kit's chart palette.

timeline
  accTitle: artoo releases
  accDescr: artoo releases from 0.1.0 in July 2026 through 0.7.0 in October 2026.
  title artoo releases
  section July 2026
    0.1.0 : artifacts, firewall, deploy
    0.2.0 : site libraries
    0.3.0 : explainer generator
  section August 2026
    0.4.0 : agent reference
    0.5.0 : forms and verification
    0.6.0 : code maps
  section October 2026
    0.7.0 : diagrams with Pele

Dates from the changelog.

Mermaid source

timeline
  accTitle: artoo releases
  accDescr: artoo releases from 0.1.0 in July 2026 through 0.7.0 in October 2026.
  title artoo releases
  section July 2026
    0.1.0 : artifacts, firewall, deploy
    0.2.0 : site libraries
    0.3.0 : explainer generator
  section August 2026
    0.4.0 : agent reference
    0.5.0 : forms and verification
    0.6.0 : code maps
  section October 2026
    0.7.0 : diagrams with Pele

Writing diagrams that hold up

Start with accTitle: and accDescr:. They become the SVG's accessible name and description; the figcaption carries the takeaway.
Name a role, not a color. gate{{Firewall}}:::accent follows the theme; style gate stroke:#3e63b4 is fixed in both. The roles are accent, warn, and muted.
Escape <, >, and & inside a hand-written HTML block. In Markdown, a ```mermaid fence needs no escaping.
Diagrams for structure, SVG for numbers. A chart that carries a quantitative claim belongs in inline SVG on the --chart-* palette, with its vintage and source.
Check it in a browser. A syntax error renders in place and logs its line and column; artoo verify --browser reports it, and artoo build fails a page that has diagram source but no renderer.

Flowchart: what artoo build does

Sequence: a deploy to GitHub Pages

State: a vendored library

Entity relationship: what a manifest records

Timeline: artoo releases

Writing diagrams that hold up

Flowchart: what `artoo build` does