Attachment
An attachment is a file kept with a card. Each one is a folder of its own under the card’s attachments/ folder, holding the file itself and a small index.md of metadata.
<card>/attachments/3f2a8c14-0000-4000-8000-000000000000/├── blob.png the file itself└── index.md its metadata---schema: 1kind: attachmenttitle: sketchextension: pngcreated: {at: 2026-07-24T18:00:00Z, by: {name: claude, kind: agent, model: opus-5}}modified: {at: 2026-07-24T18:00:00Z, by: {name: claude, kind: agent, model: opus-5}}---| Key | Type | Description |
|---|---|---|
schema | integer | Always 1. A missing value is read as 1. |
kind | text | attachment. Written when the attachment is created. |
created | stamp | When the attachment was added and by whom. Set once and never updated. |
modified | stamp | The last change to this metadata file. Renaming the attachment changes only this file. |
title | text | The original filename without its extension. Apps show title and extension joined by a dot, so sketch.png here would display as sketch.png.png. Not unique; the folder's uuid is the identity. |
extension | text | The blob's file extension, with no leading dot, such as png. It must match the blob file's name: png means the file is blob.png. If the key is absent, the file is named exactly blob. |
The blob file
Section titled “The blob file”The file is always named blob, plus a dot and its extension if it has one. The name people read lives in title, not in the file name, so renaming an attachment changes only index.md and breaks no reference.
extension and the blob’s name must agree. A folder holding blob.jpg under extension: png is reported as broken, not quietly fixed. Without the key, the file is named exactly blob.
title is the original file name without its extension. Apps show <title>.<extension>, so a title of sketch.png would show as sketch.png.png.
Adding an attachment
Section titled “Adding an attachment”- Create
attachments/in the card folder if it is missing. - Create a folder inside it named with a fresh lowercase UUID.
- Copy the file in as
blob.<extension>. - Write the folder’s
index.md.
Keep the key set to those in the table above. Put files inside attachments/, never loose beside the card’s index.md; the app moves loose files in and tells the user. A folder under attachments/ that is not named with a UUID is ignored.
Thumbnails
Section titled “Thumbnails”Next to the blob, the app writes square thumbnails named thumb.<N>.png, where N is one of the board’s thumb-sizes. A thumbnail is created the first time a body references it. See Board settings.
Embedding in a body
Section titled “Embedding in a body”Reference an attachment from a card or comment body with a relative path:
This is plain Markdown, so it renders in any viewer. A comment’s references resolve against the comment’s own folder.
Hero image
Section titled “Hero image”A card’s hero key names one of its own attachments to draw as a banner across the top of the card. It takes the attachment’s bare uuid, never a path. See the card page. A uuid that matches no attachment, or a file that is missing or not an image, draws no banner and does no harm.