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 in the source file.

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:

1-overview
2-detail
3-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 1 appears in every export. An element in frame 3 appears only from export 3 onwards. No duplication in the source file.

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

Usage

excalidraw-stages my-diagram.excalidraw

SVGs are written alongside the source file, named after the frame:

- my-diagram.excalidraw
- my-diagram-1-overview.svg
- my-diagram-2-detail.svg
- my-diagram-3-conclusion.svg

or if you set --out-dir=img:

- my-diagram.excalidraw
- img
  |- my-diagram-1-overview.svg
  |- my-diagram-2-detail.svg
  `- my-diagram-3-conclusion.svg

Multiple files and globs work too, in which case out-dir is relative to each file:

excalidraw-stages topics/**/*.excalidraw

Installation

npm install -g excalidraw-stages

Or run without installing:

npx excalidraw-stages diagram.excalidraw