MediaThe media library

The media library

Every image, video and file editors upload lives in one library. A field stores a reference to an asset, so one photo can appear in many places and be found from each of them.

View as Markdown

Uploading

Editors upload from two places. A media field takes a dropped file straight away, or opens the library to pick one. Media in the top bar shows the whole library, with an upload button and a filter for images, video and files.

The browser measures an image's dimensions on upload, and captures a frame of a video as its poster, stored as an image asset of its own. What the site can accept is config:

media.maxSizeThe largest file, in bytes. Default 25 MB.
media.acceptThe mime types offered in the file dialog and accepted on upload. Default: JPEG, PNG, WebP, AVIF, GIF, SVG, MP4, WebM and PDF.

A field narrows the list to its kind: an image field offers image types only.

The library

Selecting an asset shows its details: the filename, its size and dimensions, and four editable texts:

TitleA name for the asset in the library, searched with the filename.
AltThe alt text an image carries wherever it is used, unless a field sets its own.
Caption, CreditKept with the asset for your code to render.

Below them, Used in N places lists every page, entry and global that references the asset, from the same index that tracks references between entries.

Deleting and replacing

An asset can be deleted only while nothing uses it; the message says how many places still do. Removing the field's value, or picking another asset, clears the use.

Uploaded objects never change. Replace on a field picks a different asset for that field; the library keeps the old one until it is deleted. This is what lets the site cache media for a year: a URL always serves the same bytes.

Where files live

Uploads go to Smoodly's storage, served with a year-long cache header; until media moves fully to Smoodly the files live in a bucket Smoodly runs. The browser uploads directly to storage with a signed ticket from the admin, so a large file never passes through your app.

Next, Images and crops.

Edit this page on GitHubLast updated 14 Nov 2026