# Excalidraw

> Hand-drawn diagrams saved as files in the project.

Excalidraw is a [capability](/docs/capabilities): hand-drawn diagrams, saved as files in the project. Install it from the **Capabilities** pane and an **Excalidraw** row appears in the sidebar.

<!-- Screenshot — a drawing open on the canvas, with the Pin to card menu open. -->

## Drawings

The **Excalidraw** row opens the project's drawings, each with when it was last edited, and a field for the next one: type a name, press **Create**, and it opens on the canvas.

The list is read from the folder every time you look, so an `.excalidraw` file copied in from outside is a drawing like any other. A name already taken is refused rather than written over.

A drawing opens in a tab of its own, on the Excalidraw canvas. **Rename drawing** on the pane bar renames the file and reopens it under the new name. The canvas follows devpit's theme — light, dark, or whichever the system is using when **Appearance** is set to **System**.

## Saving

There is no save button. A drawing is written a moment after the last change.

Every write carries the time devpit last read the file, so a drawing something else changed is not overwritten. When that happens the change is not saved and the pane says so:

> `<name>` changed on disk after it was opened, so this change was not saved.

**Reload** takes what is on disk, **Keep mine** writes yours over it. While that question is open, closing the tab asks first — it is the one state where closing would lose the drawing.

A drawing file is capped at 32 MiB.

## Pinning to a card

**Pin to card** on the pane bar lists this project's cards; pick one and the drawing is pinned to it, which the pane confirms. The menu is not shown when the project has no cards.

A pin points at the file where it already is — nothing is copied. On the card, opening the pin brings the drawing back up in Excalidraw, as long as the capability is still on.

## Where drawings live

In devpit's folder for this project, as `.excalidraw` files:

```text
~/.devpit/projects/<name>-<suffix>/data/excalidraw/
```

Not in your repository. Uninstalling Excalidraw leaves them there unless you tick the box that deletes them.
