excalidraw-stages

Reads a single .excalidraw source file and generates a series of cumulative SVG exports — one per stage — for embedding in presentation slides (e.g. Marp).

This lets you reveal a diagram progressively during a presentation without duplicating elements across multiple source files.

Why

The naive approach to progressive diagram reveals is to duplicate the diagram N times in Excalidraw (once per stage). This is unmaintainable: change one element and you must update N copies.

excalidraw-stages gives you a single source of truth.

How it works

Name your frames with a numeric prefix that determines stage order:

01-overview
02-detail
03-conclusion

Each element belongs to exactly one frame — the frame where it first appears. The tool accumulates: stage N includes all elements from frames 1 through N.

An element in frame 01 appears in every export. An element in frame 03 appears only from export 3 onwards. No duplication in the source.

Elements not assigned to any frame are treated as drafts and excluded from all exports.

Usage

excalidraw-stages my-diagram.excalidraw

Output SVGs are named <source>-<frame-name>.svg and written alongside the source file:

my-diagram.excalidraw
my-diagram-01-overview.svg
my-diagram-02-detail.svg
my-diagram-03-conclusion.svg

Use --out-dir to write SVGs into a subdirectory instead:

excalidraw-stages my-diagram.excalidraw --out-dir img

my-diagram.excalidraw
img/
  my-diagram-01-overview.svg
  my-diagram-02-detail.svg
  my-diagram-03-conclusion.svg

If the source file has no frames, the entire file is exported as a single my-diagram.svg.

Multiple files and glob patterns work too:

excalidraw-stages topics/**/*.excalidraw --out-dir img

Options

| Option | Description | |-----------------|-----------------------------------------------------------------------------------------------| | --out-dir dir | Write SVGs to dir/ relative to each source file. Created if missing. | | --embed-fonts | Base64-embed Excalifont and Cascadia into each SVG (fully self-contained, larger files). | | --init | Print @font-face declarations for Excalifont and Cascadia. Paste into your host HTML once. |

By default, SVGs reference fonts by family name only. The Marp plugin provides the required @font-face declarations automatically; use --init if you need them in a non-Marp context.

Installation

npm install -g @goalwards/excalidraw-stages

Or run without installing:

npx @goalwards/excalidraw-stages my-diagram.excalidraw