Files and images

What this covers

The Images section of the page form: how to upload, where files live on disk, how the title field doubles as alt text, what thumbnails are generated, and the two common cases that trip people up (uploading on a brand-new page, and re-ordering images after they are saved).

Walkthrough

Step 1: Find the Images section

Open a page in the Pages module. Scroll past Content; the Images label appears with an info line ("only images with the extensions jpg, gif or png are allowed") and the FilePond uploader below.

If the page already has images, each one shows as a row above the uploader: a thumbnail, a title input, a position handle, and a remove button.

Step 2: Upload

Two ways to add files, both batch-capable:

Drag and drop: select multiple files in your file manager (Cmd-Click / Shift-Click on macOS, Ctrl-Click / Shift-Click on Windows and Linux), then drag the whole selection onto the FilePond widget. All files queue together.
Browse button: click Select picture to open a file picker. Hold Cmd / Ctrl while clicking to select multiple files, or Shift-Click to select a range; click Open.

Each file uploads as soon as it is staged (existing page) or is held until the first save (new page; see "deferred uploads" below). The status of each upload appears next to the file name; once finished, the file moves into the rows list above the uploader and shows the thumbnail.

Step 3: Give each image a title

Type a short description into the title input next to each image. The title doubles as:

the alt text the rendered <img> tag uses (search engines, screen readers, slow connections);
the caption a theme prints under the image when it walks the file list (the default markdown rendering shows the title as a caption when present).

You can leave the title empty; the rendered alt falls back to the file name in that case, which is rarely what you want.

Step 4: Save

Click Save at the bottom of the page form. Title changes and position changes are persisted as part of the page save, in the same request. The Images section reloads with the new titles applied.

Step 5: Reorder by drag handle

Each image row has a small drag handle on the left. Drag a row up or down to change its position. The order is what the theme sees: a foreach ($page->images as $img) loop visits them in this order.

After reordering, Save to persist the new order. The order is shared across all editors; once saved, every visitor sees the same sequence.

Step 6: Remove an image you no longer need

Click the remove button on the image row. The image is queued for deletion; Save to apply. The file is removed from public/uploads/<categoryId>.<fieldId>.<itemId>/ and the matching thumbnail under public/uploads/<categoryId>.<fieldId>.<itemId>/thumbnail/ is deleted alongside it.

What to check after

The image shows in the page row list with a thumbnail.
The title field has the text you typed (or is intentionally empty).
The position handle is in the order you want.
Visiting the page on the frontend renders the image; the rendered alt attribute matches the title you set.

Troubleshooting

Upload says "Pending" forever on a brand-new page

You are seeing deferred-upload mode. A new page does not have an id yet, so FilePond cannot upload until the page is saved. Click Save at the bottom of the form; the page save returns the new id, and FilePond then uploads each staged file in sequence. The page reloads and the images appear in the row list.

If saving the page does not trigger the upload, the page save itself failed (CSRF, validation, duplicate name). Look for an error message at the top of the form.

"Error while uploading images"

Three common causes:

Wrong file type. Only .jpg, .png, .gif are accepted by default. The validation is per-field; a custom plugin can widen the list, but the core Pages module sticks to those three.
File larger than the upload limit. PHP's upload_max_filesize and post_max_size cap the size. The editor surfaces a generic error; raise both ini values for bigger uploads and restart PHP.
public/uploads/ directory not writable. Uploads land under public/uploads/<categoryId>.<fieldId>.<itemId>/; the web server's user needs write access to public/uploads/. chmod -R u+w public/uploads/ (or chown to your web server's user) fixes it.

Thumbnails do not appear in the row list

Thumbnails are generated lazily on the first request that asks for them. If the thumbnail directory is not writable, the editor falls back to the full-size image at thumbnail dimensions (slow but functional). Check that public/uploads/<categoryId>.<fieldId>.<itemId>/thumbnail/ is writable.

An image I uploaded shows up on the wrong page

Image fields are per-page; an upload on Page A cannot end up on Page B. If you are seeing the same image on two pages, you likely uploaded it twice (once per page). To share an image across pages, upload it once and reference it by URL in the markdown content of the other pages, or use a plugin that provides a shared media library.

I re-uploaded an image but the browser still shows the old one

The nginx layer in front of public/uploads/ ships an aggressive cache policy (30 days, Cache-Control: public, immutable). The immutable directive tells the browser to trust the cache without ever revalidating, so a re-upload that keeps the same filename (and therefore the same URL) is invisible to anyone who already loaded the original.

Workarounds today:

Hard-reload in the browser (Ctrl-Shift-R / Cmd-Shift-R) to bypass the cache once.
Rename the file before re-uploading: holiday-v2.jpg gives the upload a fresh URL that no cache has seen.

Fixing it properly is a Scriptor-side change: drop immutable from the /uploads/ location in docker/nginx.conf so the existing ETag + Last-Modified headers can do their job (browser revalidates on its own schedule, gets 304 Not Modified when nothing changed and the full response when the file did change). Tracked as a known issue against the cache contract; this page will be updated when the fix lands.