Media

The media library holds every image, document, font and video the site uses. Files are stored on the server's disk; the database keeps their descriptions and the list of generated sizes. Open it under Media.

Uploading

Upload, or drag files onto the library. Each file may be up to 64 MB. Images in JPEG, PNG, WebP, BMP, TIFF or AVIF are resized after the upload returns (the item shows "Sizing…" meanwhile); everything else, including SVG and animated images, PDFs, fonts and video, is served exactly as uploaded. The library's search matches file names, alt text and captions.

Generated sizes

Every resizable image gets these sizes, whether it was uploaded or imported, never wider than the original, so a 500px image gets only thumb and a 500px small:

Size	Width
thumb	320px
small	640px
medium	1024px
large	1600px
hero	2400px

Sizes are JPEG at quality 82, or PNG when the image has transparency. Images are turned upright first, so photos from phones are the right way up. The image widget's size names the size the image is shown at, and the browser chooses among all of them for the screen it is on.

Imports make the sizes as they go: installing a theme kit and importing a site folder size each new image before they finish, from the admin or the command line, with or without a server running. An image an earlier import left without sizes gets them the next time its site folder is imported.

Next-generation copies

WebP and AVIF copies are made when someone asks: Optimise on an item, or "Optimise all" for every image not yet optimised with the current settings. They are made one image at a time in the background, from the original rather than from a JPEG size, at the same widths. Without a module choosing otherwise, Gansey makes WebP at quality 80. A module can choose the formats (WebP, AVIF or both) and qualities; the official Performance module does, and can optimise new uploads as they arrive. Those choices apply only while that module runs.

Each item records the settings its copies were made with, so after a change the library shows which images are out of date ("Optimised with older settings"); "Re-encode everything" makes every copy again. Pages offer AVIF first, then WebP, then the JPEG or PNG, so a browser takes the best format it understands.

Alt text, captions and focal points

Select an item to give it alt text (a description for people who cannot see the image) and a caption. Image widgets use them unless the widget sets its own; galleries use them too. Click a spot on the preview to set the focal point: images cropped to a fixed shape, by the image widget's aspect or a gallery's ratio, keep that spot in view. Images without alt text are marked in the library.

The details panel also lists the pages that use the item. An item a published page still shows cannot be deleted; the panel says which pages to change first.

Where files live

Files live under the media root: [media] root in gansey.toml, or GANSEY_MEDIA_ROOT, by default ./data/media.

originals/2026/10/<media id>.jpg
variants/2026/10/<media id>/medium.jpg
variants/2026/10/<media id>/medium-1a2b3c4d.webp

They are served from /media/... with a year-long cache lifetime. Every address contains the item's id, and next-generation copies are named after their content, so making them again gives new addresses and browsers never keep a stale file. Backups include the media root.