Drawings

An Excalidraw canvas in the vault: a drawing is a note that opens as a whiteboard, embeds as a picture, and keeps working in Obsidian.

Excalidraw is a free whiteboard tool: shapes, arrows, freehand strokes and text, in a hand-drawn style. A drawing in Astrolabe is a file in the vault in a format Excalidraw already speaks: either the editor's own .excalidraw file (a plain data file), or the shape the Obsidian Excalidraw plugin writes into a markdown note, .excalidraw.md. Astrolabe did not invent a third format. Both open here as a full Excalidraw canvas in a pane, both save back into the same file, and both keep opening in Obsidian afterwards.

A drawing is a note by every other measure: it sits in the tree with a pencil beside its name, it is a tab beside the notes you are writing, the words on its canvas are in search, and a [[wikilink]] typed into a text element counts in the graph and the backlinks. It is a picture by one measure only: it never opens in the text editor.

Making one

The pencil at the top of the notes sidebar starts a drawing in the vault's root, or in the Drawings folder named in the Writing section of Settings (behind its Advanced line). Right-click a folder → New drawing here puts one inside that folder, and New drawing in the command palette lands in the open note's folder. The name prompt offers Drawing.excalidraw, and the extension decides the format:

From inside a note, type /draw. The slash menu makes the drawing beside the note, named after it (Essay sketch.excalidraw, then sketch 2…), writes the ![[embed]] where the caret was, and opens the canvas in a pane next to the note, so you draw with the prose in view and the embed fills in as you save. No separate note, nothing to paste.

Type either extension yourself to choose. A drawing made in Obsidian, compressed or not, opens without conversion. When Astrolabe saves a plugin file it keeps the frontmatter, keeps the compression if the file had it, and lists the text elements under ## Text Elements where the plugin does, so Obsidian's own search and links keep working on what Astrolabe drew.

Drawing

The menu in the corner (≡) carries the actions a drawing in a vault has a use for: export an image, find on the canvas, the command palette, help, clear the canvas, and the canvas background. Excalidraw's own links and its theme switch are not there; the canvas follows Astrolabe's theme. Dialogs open centred on the canvas, not the window, and the sidebar stays clear.

The canvas is Excalidraw, whole: shapes, arrows, freehand, text, images, the library, and every one of its keys (r rectangle, t text, v select, ? for the rest). It wears Astrolabe's colours, so dark or light follows the theme you are in, and it speaks the editor's language: an Arabic interface gets Excalidraw in Arabic, mirrored. Its fonts are served from your own server; no request leaves it.

It saves like a note. A stroke lands in the file about a second after the pen lifts, under the same rule every note save keeps: if the file changed on disk in the meantime (Obsidian, a git pull, another window), the save is refused and a strip offers Keep mine or Use the disk version. Nothing drawn is dropped either way; the canvas holds your strokes until you decide. Closing the tab or the window flushes what is pending. The corner says Saving…, Saved or Unsaved strokes, and nothing else.

Every save leaves a picture beside the file, Drawing.excalidraw.svg, exported by Excalidraw itself with its fonts inlined. That svg is what every other surface shows.

Embedding a drawing

![[Drawing.excalidraw]] (or ![[Drawing.excalidraw.md]]; ![[Drawing]] finds it too) puts the picture in a note, sized like an image and taking |300 the way an image embed does. The editor's live preview, the reading view, a blog article, a designed page and a library lesson all draw the exported svg; none of them loads the canvas.

A visitor sees the svg of a published note's embed exactly as they see any other attachment of that note: the drawing itself is a note, and an unpublished one is not served at all, but the picture beside it walks through the note's own door. Unpublish the note and the door closes.

If the picture is not on disk yet (a drawing made in Obsidian with auto-export off, or a file older than this feature), you, the owner, see it anyway: the reading view draws it with the canvas code, once, for that page. Open the drawing and save it once and the picture exists for everyone.

What is indexed

The text elements, one per line, and a [[link]] set on any shape. Not the file's internal data: an element id is not a word anyone searches for. So a drawing appears in search by what is written on it, in the graph by what it links to, and in a note's backlinks when the drawing names that note.

In Obsidian

Everything here is the plugin's own format, so the plugin sees a drawing Astrolabe made as one of its own. Obsidian's core app (without the plugin) shows a .excalidraw.md as a markdown note whose scene is folded in a %% comment, which is what the plugin's files have always looked like there. A plain .excalidraw is an attachment to Obsidian, as it always was. The other things Astrolabe adds to a note behave the same way there: a tracker and a sigil go back to being labelled code blocks, and an orbit writes its schedule in the Spaced Repetition plugin's own format.

Under the hood: shared/drawing.ts reads and writes both spellings (tests/drawing.test.ts); client/drawing/DrawingSurface.tsx is the pane; PUT /api/drawing-svg?path= is the picture's door; scripts/check-bundle.mjs asserts the canvas is never loaded with a page's first paint.