Excalidraw Script Engine Coding Example: Building a Gallery View

A working Excalidraw automation script can turn an Obsidian vault of YouTube thumbnails (and optional storyboard notes) into a clickable, grid-style “gallery view” on an Excalidraw canvas—without manually dragging images one by one. The core payoff is speed plus structure: the script scans the vault for thumbnail files, sorts them by creation time, pairs each thumbnail with its matching storyboard markdown (when present), then lays everything out in a 12-column matrix with consistent spacing and aspect-ratio-friendly sizing.

The workflow starts by creating an empty Excalidraw drawing and attaching Excalidraw Automate to the active window via the developer console. From there, the script derives the target folder path from the current file’s path and name, then builds a list of candidate thumbnail markdown files. It filters by two conditions: the file path must start with the computed folder path, and the file base name (lowercased for casing tolerance) must contain the word “thumbnail.” In the author’s vault, this yields 145 thumbnail-related markdown files.

Sorting matters because thumbnails need to appear in chronological order rather than arbitrary filesystem order. The script uses each file’s `stat.ctime` (creation time) and converts it into a Moment-formatted date string for comparison. After an initial reversal mistake, the sort logic is flipped so the oldest items come first—confirmed by checking the first element corresponds to an older video date.

Next comes the pairing step: for each thumbnail file, the script searches for a corresponding storyboard markdown file in the same folder. It does this by reusing the folder path and filtering for markdown files whose base name matches “storyboard.” If a storyboard exists, the script grabs the first match; if not, it keeps the storyboard value undefined using a safe optional approach.

The layout step is where the script becomes practical. It defines a grid placement function that computes row and column coordinates using modulo arithmetic (the grid uses 12 columns). Each thumbnail is added to Excalidraw with `EA add image`, then the image element is updated so its link becomes a markdown link to the storyboard file path—making each thumbnail clickable and navigable to the storyboard.

Asynchronous image loading introduces real-world friction. An initial attempt using a bulk “add elements” approach starts loading images in the background and can lead to timing issues, distorted sizing, and confusing console behavior. The final, reliable version switches to a sequential `for` loop that awaits each image load before placing the next one. That change prevents race conditions and results in a clean matrix where all images appear and links work.

By the end, the canvas contains the full gallery of thumbnails arranged in rows and columns, with storyboard links attached per image. The author’s takeaway is that Excalidraw Automate can be used to automate repeatable knowledge-management workflows inside Obsidian—turning a messy manual process into a deterministic script-driven layout.