Clew Manual

Reading mode

Drawings (Excalidraw)

Clew has its own canvas, and for most work it is the better tool. But Excalidraw is what hundreds of thousands of people draw in, and an Obsidian vault is very likely to be full of .excalidraw.md files. Clew opens them, edits them, and hands them back in a form Obsidian still reads — using the real Excalidraw, embedded unmodified.

Opening a drawing

Click one in the file explorer, or follow a [[link]] to it. Both the Obsidian form (.excalidraw.md) and the plain JSON form (.excalidraw) open in the editor rather than as a wall of text. The editor is Excalidraw itself: the same tools, the same keyboard shortcuts, the same library format, behaving exactly as it does on excalidraw.com. Nothing about it is a reimplementation, which is deliberate — it means an Excalidraw release improves Clew's drawings without anyone here touching them.

Creating one

File → New Drawing (Excalidraw), the command palette, or right-click a folder in the file explorer. The new file carries the frontmatter key Obsidian's plugin looks for, so a drawing made in Clew opens as a drawing there too.

Two extensions, and which to choose

ExtensionWritten byWhy it exists
.excalidraw.mdObsidian's plugin, and Clew by default Markdown is the only thing Obsidian indexes, so the wrapper is what gives a drawing backlinks, tags and searchable text there
.excalidrawClew, on request Plain JSON — the honest extension for a vault Clew has to itself

Set excalidrawFormat under Settings → This vault to choose; the default is Obsidian's convention, because a shared vault should look native in both apps.

In Clew the choice costs nothing Clew reads the words straight out of the drawing rather than out of a markdown wrapper, so both forms are indexed identically. A [[wikilink]] typed inside a drawing is a real link — it appears in the target's backlinks and in the graph — and a #tag inside a drawing is a real tag. The wrapper is Obsidian's workaround for its own indexer, not something Clew needs.

Embedding a drawing in a note

![[diagram.excalidraw]] on its own line renders the drawing inside the note. An embed is read-only: reading a note should not put you one stray click away from altering a diagram. The title bar above it opens the real editor when you do mean it.

Embeds are built only as they come into view, because each one is a full editor instance — a note holding six diagrams does not start six of them at once.

Drawings on a canvas

A drawing dropped onto a canvas becomes a file node like any other, and there it is editable — double-click to engage the node and draw. A canvas is a workspace, and its node content is inert until engaged anyway.

Shape libraries

Drop a .excalidrawlib onto the canvas, or use Load library in the library panel. Clew remembers it in .clew/excalidraw-library.json, per vault: Excalidraw on its own keeps libraries in browser storage, which in a note app means "until something clears it". A shape set is a working vocabulary that belongs with the notes it illustrates — flowchart shapes in the project vault, anatomy in the teaching one — so it travels when the vault does.

Note that dragging a library file in from Finder does not copy it into the vault; Excalidraw reads its contents and Clew stores the shapes. The .excalidrawlib stays wherever you downloaded it.

What is preserved when you save

This is the part that makes a shared vault safe. Clew does not rebuild an Excalidraw file — it splices the drawing back into the file it came from and leaves every other byte alone:

Images inside drawings

Obsidian's plugin stores a pasted image as an ordinary vault attachment: the drawing keeps only a file id, and the markdown's ## Embedded Files section maps that id to a wikilink. Clew reads that section, resolves each link the way a wikilink click resolves, and loads the image into the drawing — so a vault full of illustrated drawings looks in Clew the way it looks in Obsidian. Saving reverses the trick: the image bytes are never copied into the markdown, the section is left as it was, and the attachment stays the single copy.

Drawings that carry their images inside the scene — the files map of dataURLs that excalidraw.com exports and some plugin configurations write — work too, and round-trip unchanged. An embedded entry that is not an image (the plugin can also transclude notes and areas of other drawings this way) shows Excalidraw's own missing-image placeholder rather than a wrong rendering.

An unedited drawing saves back byte-for-byte, and nothing is written until you actually draw something — so opening a drawing to look at it never shows up as a change in git or sets a sync going.

Round-tripping is the point Edit a drawing in Clew, open it in Obsidian, edit it there, come back. If anything is lost in that loop it is a bug worth reporting, because the whole surface exists to make it safe.

See also