Mermaid Diagrams

This experiment turns fenced Mermaid text into diagrams. Quartz prepares diagram containers and copyable source during the build; the browser must then finish loading the client-side code before those containers become SVG drawings. The same page can therefore have valid build-time markers but zero completed SVGs in an early browser capture. The sandbox contains both a flowchart and a sequence diagram, so it also demonstrates more than one Mermaid grammar on a page.

The following is copied verbatim from /home/loca/dev/quartz-sandbox/sandbox/engine/quartz.config.yaml, lines 78–94. It is the actual enabled plugin block, not the shorter illustrative configuration printed in the sandbox article:

  - source: "@quartz-community/obsidian-flavored-markdown"
    enabled: true
    options:
      comments: true
      highlight: true
      wikilinks: true
      callouts: true
      mermaid: true
      parseTags: true
      parseBlockReferences: true
      enableInHtmlEmbed: false
      enableYouTubeEmbed: true
      enableTweetEmbed: true
      enableVideoEmbed: true
      enableCheckbox: true
      enableObsidianUri: true
    order: 30

These are the exact two active Mermaid fences from /home/loca/dev/quartz-sandbox/sandbox/vault/experiments/mermaid-diagrams.md, lines 56–62 and 67–77. The outer four-backtick fence here shows the sandbox source rather than creating a second live experiment in this documentation page:

```mermaid
flowchart TD
  A["quartz.config.yaml"] --> B["install-plugins"]
  B --> C["plugin index (.quartz/plugins/index.ts)"]
  C --> D["bootstrap-cli.mjs build"]
  D --> E["dist-<epoch>/"]
```

```mermaid
sequenceDiagram
  participant O as Operator
  participant B as build
  participant D as dist
  O->>B: install-plugins
  B->>B: regenerate plugin index
  O->>B: bootstrap-cli build
  B->>D: emit HTML routes
  D-->>O: serve on 127.0.0.1
```

What the rendered output proves

Live experiment: https://quartz.loca.zone/experiments/mermaid-diagrams.

The historical sandbox-experiments.json receipt, under /home/loca/dev/quartz-sandbox/evidence/2026-09-15-quartz-migration-f1fd35c3/, records the emitted route /experiments/mermaid-diagrams.html with title Mermaid Diagrams — Quartz Sandbox. Its classified proof_markers are exactly mermaid_class: 5, data_clipboard: 2, mermaid_svg: 0. The matching browser entry also records clipboard_button: 4, syntax_figures: 2, reading_stats: 1, reading_words: "266" and reading_minutes: "2". The receipt’s mermaid_class is a recorded marker counter, not a statement that five separate diagram elements were drawn.

That earlier capture used a 5-second virtual-time budget on a temporary loopback server. It does not prove a completed SVG render. Main subsequently observed two rendered SVGs on the public route with a 15-second budget. This documentation author independently repeated the public-route capture on 2026-09-16:

Observation	Result
HTTP fetch	200; title Mermaid Diagrams — Quartz Sandbox
First documentation capture, in a two-worker route sweep with a 15-second budget	mermaid_containers: 2, mermaid_svg_descendants: 0; retained as an incomplete client-render observation
Subsequent standalone capture with a fresh profile and the same 15-second budget	Chrome exit 0; mermaid_containers: 2, mermaid_svg_descendants: 2, clipboard_buttons: 4
Standalone rendered DOM	75076 bytes; SHA-256 c7f875a9d6af0b06b4910ab4615cfdac43814352ede4b5c891340baf1a8ec7be

The independent SVG count counts actual <svg> descendants of elements whose class tokens include mermaid; it does not count source text, unrelated icons or the global fullscreen container. Thus the final capture proves that both diagrams were drawn on the live route. It does not establish fullscreen interaction, successful copying, accessibility or a guaranteed render deadline.

The reason to preserve both zero and two is the build/browser split: the browser must finish client-side loading and Mermaid execution. A virtual-time budget is not a semantic “diagrams ready” condition. The first documentation sweep also shows that increasing that budget alone does not guarantee completion under every loading schedule. No sandbox code changed between those captures, and these measurements do not identify which individual resource or scheduling event delayed the zero-SVG capture.

Safe for the shared engine?

Recorded classification: safe_for_shared_engine: true.

Receipt reason, verbatim:

It is a per-page feature of a transformer already enabled by the shared engine; pages without Mermaid fences are unaffected.

This is a recorded assessment, not deployment authority. A true verdict does NOT authorize changing the shared engine at /home/loca/dev/quartz/quartz, which powers 51 wikis. If a change there is required, report it as a BLOCKER, not an action.

Try it in the sandbox

Edit only the isolated sandbox source for an authorized experiment, then use its build-and-publish wrapper:

cd /home/loca/dev/quartz-sandbox/sandbox && ./build.sh

The wrapper checks commit 3dff48b5df6d84c9544a5ae19c8f2cbb01dc44e5 and confines the engine to the sandbox project. Its nonblocking .build.lock covers install-plugins before bootstrap-cli.mjs build, with --directory /home/loca/dev/quartz-sandbox/sandbox/vault and --output pointing to a fresh sandbox/dist-<epoch>. It requires index.html, atomically swaps sandbox current, and retains the new plus two prior timestamped releases. The origin adopts the release on the next request without a restart. These are the real wrapper and sandbox-runtime.json runtime contract, not steps performed while writing this documentation.

The runtime receipt records this invocation; it is reference only, because the deployed service already owns port 51947. Do not start a second process or restart the service:

PATH=/usr/bin:/bin PORT=51947 SANDBOX_ROOT=/home/loca/dev/quartz-sandbox/sandbox/current NODE_ENV=production /usr/bin/node /home/loca/dev/quartz-sandbox/sandbox/serve.mjs

The successful independent rendered capture used this exact command and a fresh temporary profile:

/usr/bin/google-chrome --headless --no-sandbox --disable-gpu --user-data-dir=/tmp/sandbox-wiki-mermaid-single-6y1rq5_o --virtual-time-budget=15000 --dump-dom https://quartz.loca.zone/experiments/mermaid-diagrams

The capture profile was removed afterwards. Use a new unique temporary profile for another capture, and inspect actual SVG descendants before calling the diagrams rendered; HTTP 200 or source containers alone are insufficient.

index