obsidian-excalidraw

Obsidian Excalidraw

Generate .excalidraw files programmatically and embed them in Obsidian markdown notes.

Quick start

Use the helper module in scripts/shapes.js — it generates valid Excalidraw JSON with no dependencies:

# Run the working example to generate a diagram
node examples/example.js > my-diagram.excalidraw

# Inspect or validate generated JSON with jq (never python)
node examples/example.js | jq '.elements | length'
node examples/example.js | jq '.elements[] | select(.type == "arrow") | .id'

Or require it in your own script:

const ex = require('./scripts/shapes');

const elements = [
  ...ex.node('alpha', 100, 80,  180, 70, 'Alpha\n(primary)'),
  ...ex.node('beta',  400, 80,  180, 70, 'Beta\n(secondary)', { strokeStyle: 'dashed', strokeColor: '#6b7280' }),
  ex.arrow('a1', 'beta', 'alpha', [490, 115], [190, 115]),
  ex.floatingLabel('l1', 290, 90, 'depends on'),
];

require('fs').writeFileSync('diagram.excalidraw', JSON.stringify(ex.document(elements), null, 2));
// shapes.js lives in scripts/ — adjust the relative path if requiring from elsewhere

Embed in any Obsidian note:

![[diagram.excalidraw]]

How Obsidian stores Excalidraw files

Write .excalidraw JSON → Obsidian converts it to .excalidraw.md. The original .excalidraw disappears. The .excalidraw.md format wraps compressed JSON with a plaintext text-elements section (for Obsidian search/backlinks). On a filesystem-writable vault, no need to produce this format — write plain JSON and let the plugin convert.

iCloud vaults are the exception. Vaults under ~/Library/Mobile Documents/ cannot be written on the filesystem (macOS blocks the process — see "Writing to the vault" below). There you must write the .excalidraw.md form through the Obsidian CLI.

![[name.excalidraw]] embeds resolve to name.excalidraw.md automatically.

A live scaffold example of the converted format is in references/obsidian-file-format.md.

See references/obsidian-file-format.md for the full format breakdown and decompression instructions.