Media Library

The media library holds every image you use across the site. Upload once, then insert into pages, posts, and blocks from the same picker everywhere. This page covers uploading, the automatic size variants, the per-image details you can edit, and how deletion behaves when content references a file.

Uploading

In the admin Media area, choose Upload and select one or several files at once (each up to 10 MB).
Accepted image types: JPEG, PNG, GIF, and WebP. Anything else is rejected (documents like PDFs and Office files belong to the Documents module; form file-upload fields have their own accepted set).
A few safety checks run on every upload before the file is visible anywhere:
- The file must be what its type claims: contents are inspected, not just the declared extension. A renamed file with mismatched contents is refused.
- An identical file already in the library is refused with a pointer to the existing item (“already stored as …”), which prevents accidental duplicates.
The stored filename is randomized on the server; the name you see in the library is the original filename you uploaded, which you can change later.

What happens after upload

Processing runs in the background the moment your upload finishes:

Images are optimized. JPEGs are re-compressed at a good web quality; PNGs are re-compressed at maximum compression. This happens once, server-side.
Responsive sizes are created. For JPEG and PNG images wider than 320 px, the library generates 320, 640, and 1280-pixel versions: each as the original format and additionally as WebP. Themes use these to serve appropriately sized images to phones and desktops automatically.
Dimensions are recorded (pixel width/height), shown in the item details.
If an image is dramatic in dimensions (over 10,000 pixels either way), it’s refused as a possible decompression attack rather than taking the server down.
GIFs and WebP are stored as-is; no re-compression or sized variants are created for them.

The library view

Folders let you organize: assign a folder name to any image, and the sidebar lists all your folders for quick filtering.
Search looks across original filename, alt text, and stored filename. Sort by newest, name, or file size.
The per-page count is large (100 items; 50 when opened as a picker from the editor).
Opened as a picker inside the page/post editor, the library behaves as a chooser: picking an image inserts it into the content at the cursor.

Details you can edit per image

Open an item to edit:

Filename (display name) and alt text: alt text describes the image for screen readers and SEO; it defaults to the original filename at upload and is worth filling in deliberately.
Folder, caption, and credit: caption and credit are available to themes for display purposes.
Replace the file: upload a new version of the image in place. The filename stays the same, so every page and block already referencing the image keeps working, and the optimization/variant pipeline runs again on the new file. Replacing is limited to admins or the person who uploaded the image.
Usage report: the item’s page shows everywhere it’s referenced across your content, with links into each item.
Revisions: metadata changes are snapshotted, so prior names/alt-text can be rolled back remotely like other content revisions.

Deleting

Deleting moves items to trash, with an immediate undo link and restore from trash afterwards.
A file that’s referenced by live pages, posts, or blocks cannot be deleted; the errors name the referencing pages so you can remove those usages first. Only genuinely unused files can be trashed, then deleted permanently.
Export the library’s metadata as a JSON file (useful for an inventory or as a starting point for a migration), and admins can import metadata from that same format back.

Practical guidance

Fill in alt text at upload time: it defaults to the filename, which is rarely reader-friendly.
Prefer uploading the highest-resolution image you have (up to 10 MB): the library derives the smaller sizes itself, so keeping the original large file as the master means the responsive set stays consistent.
Folders are organizational only: moving an item to a folder doesn’t change its URL or any existing references.