Media

Lamb lets you add images to posts without leaving the editor. Uploaded files are stored under src/assets/YYYY/MM/ and served from your own site — there is no external image host.

Adding images

When logged in, there are two ways to add an image to the post editor:

Drag and drop one or more image files onto the editor textarea.
Paste an image straight from the clipboard, for example a screenshot.

Either way the file is uploaded and a markdown image link (![name](url)) is inserted at the cursor. Pasted screenshots arrive without a real filename, so each is given a unique name before upload.

Supported formats

These image types are accepted:

jpg, jpeg, png, gif, webp, avif

SVG is not accepted, because SVG files can carry scripts.

WebP conversion

To keep stored files small, JPEG and PNG uploads are automatically re-encoded to WebP. The markdown link inserted into your post points at the converted .webp file. Transparency in PNGs is preserved.

gif, webp, and avif uploads are stored as-is:

GIF may be animated, and converting would flatten it to a single frame.
WebP and AVIF are already efficient formats.

If conversion ever fails (for example on a server whose PHP GD extension lacks WebP support), Lamb falls back to storing the original file unchanged, so uploads never break.

Micropub uploads

Images sent via Micropub — both inline photo files on a post and files sent to the media endpoint — go through the same storage and WebP conversion as editor uploads.

Server requirements

Uploads require the directory src/assets/ to be writable by the web server or PHP-FPM user.

Upload size limits

Because uploads are converted to WebP and resized server-side, the original file size mostly doesn’t matter — large phone photos are fine. What limits the upload is the server configuration:

PHP caps uploads with upload_max_filesize (default 2M) and post_max_size (default 8M). The Lamb Docker images raise these to 20M / 25M; on other hosts raise them in php.ini or a conf.d file.
NGINX additionally caps the request body with client_max_body_size (default 1m). The shipped .nginx/snippets/lamb.conf sets it to 25m.

If an upload over the limit fails, it fails silently from the editor’s point of view — check the server limits first when a large image won’t upload.

WebP conversion relies on PHP’s GD extension being built with WebP support. This is the common default, but it isn’t guaranteed on every host. WebP support is the only thing the conversion needs — if it’s missing, nothing breaks: Lamb stores each upload in its original format instead, so JPEG and PNG files are saved as-is rather than being converted. You simply don’t get the smaller WebP files.

Checking for WebP support

Run this on the server (the same PHP binary your site uses):

php -r 'echo function_exists("imagewebp") ? "WebP: yes\n" : "WebP: no\n";'

For more detail, inspect GD’s reported capabilities:

php -r 'print_r(gd_info());'

Look for [WebP Support] => 1 in the output. 1 means uploads will be converted; 0 (or a missing line) means they’ll be stored in their original format.

If you can’t run the CLI — for example on shared hosting where only the web server’s PHP is configured — drop a one-line script such as phpinfo(); into a temporary file in src/, load it in your browser, and search the page for “WebP” under the gd section. Delete the file afterwards.

If WebP support is missing and you want it, install or enable the WebP-capable GD build for your platform (for example apt install php-gd on Debian/Ubuntu, which bundles WebP support in current releases) and restart PHP-FPM or your web server.

Post Types: Add images to status and page posts.
Micropub: Publish posts and upload photos from external apps.
Social Embeds: A post’s first image becomes its social preview card.
Themes: Uploaded files live in src/assets/, not in theme directories.