ADR 0018: Excalidraw diagrams rendered to SVG with headless Chrome
- Status: Accepted
- Date: 2026-10-20
Context
ADR 0017 renders the documentation diagrams with Mermaid. The maintainer wants the diagrams in the hand-drawn style of Excalidraw, which the Mermaid output cannot produce.
Excalidraw has no VitePress plugin, and embedding its editor would add React to a Vue site (ADR 0017). The options were:
- Draw the scenes in Excalidraw, and render them to SVG with
@excalidraw/utils, which needs a browser to measure text. - Write the SVG by hand, without new dependencies. The result does not look like Excalidraw.
- Draw the scenes on excalidraw.com and commit the exported files.
The maintainer chose option 1. Its new development dependencies need the maintainer's approval (AGENTS.md), which was given.
Decision
- Sources are
.excalidrawfiles indocs/diagrams-src/. They open and edit in excalidraw.com. Each source has a top-leveltitlestring, which becomes the accessible name of its SVG. - Rendering is done by
scripts/render-diagrams.mjs. It bundles@excalidraw/utilswith esbuild and runs the export in Chrome or Chromium, controlled through the DevTools protocol. The script writesdocs/public/diagrams/<name>.svg. - Browser lookup: the
CHROME_PATHvariable when set, then the default install locations of Windows and macOS, then thePATH. Without a browser the script stops with an error that namesCHROME_PATH. - Dependencies, pinned exactly:
@excalidraw/utils0.1.7 andesbuild0.28.2, as devDependencies. The script runs on Node.js 22.18 or later, which provides theWebSocketglobal it uses. - Committed output. The SVG files are committed, so building the site does not need a browser. CI does not render diagrams.
- Waiting for the export. The script waits for the promise returned by the export through the DevTools protocol. It does not read the DOM after a fixed time, because that returned before the export finished.
- Backgrounds. Scenes are exported with an opaque white background, so each diagram reads the same in the light and dark themes of the site.
- Corners. Rectangles use
roundness: { type: 3, value: 12 }, a smaller fixed radius than the Excalidraw default of 32. - Sequence diagrams stay in Mermaid. A sequence diagram is kept as a Mermaid block in its page, rendered by
vitepress-plugin-mermaid(ADR 0017). Each tool call sits in its ownrectblock, with translucent fills that read in both themes.
Consequences
- Re-rendering needs a Chrome or Chromium binary on the machine that runs the script. Setting
CHROME_PATHon a CI runner is enough to render there. No CI job renders today; a check that the committed SVGs match a fresh render is a separate decision. - The export bundle is about 20 MB while it runs. It is not committed.
- Excalidraw does not keep unknown top-level fields when it saves a file. A source re-saved on excalidraw.com or in the VS Code Excalidraw editor needs its
titleadded back, and the script fails with a message when it is missing. - Mermaid and
vitepress-plugin-mermaidstay installed for the sequence diagrams. For every other diagram, this decision replaces the diagram part of ADR 0017.