Image scaling Last updated: 23. Oct 2026
How scaled image URLs work, which sizes a site accepts (images.sizePolicy), and the scaling modes.
Scaling URLs and allowed sizes
Image URL: /path/photo.jpg/WxHxM/seo-name.jpg. Without any restriction the site accepts any size (each unique size costs CPU plus its own cache entry). The images.sizePolicy key in site.json controls how sizes are enforced.
The WxHxM key: W = width in px, H = height in px. 0 on ONE axis means no limit on that axis — the axis is derived from the image's aspect ratio, so 1400x0 means at most 1400 px wide. 0x0 means no scaling at all: the source is served as it is — use linkFile instead. Negative values return HTTP 400. M = scaling mode (0 = ScaleToFit default, 1 = ScaleToFill, …). "1200x800" is treated as mode 0.
Size policies (images.sizePolicy)
Policy | Behaviour |
|---|---|
| Any size. Only |
| Accepts |
| An unknown size returns HTTP 400 (unless |
Size cap (images.maxDimension): a width or height above the cap returns HTTP 400 under every policy, open included. The default is 2000 px; set images.maxDimension in site.json to change it. A free axis (0) is checked against the cap once it has been derived from the image.
Unknown sizes (images.onDisallowed): decides what auto and strict do with a size that is not on the list — "nearest" serves the nearest allowed size with the same mode, "reject" returns HTTP 400. When it is not set, auto uses nearest and strict rejects.
Admin (the 'Image sizes' tab in folder properties): choose policy/cap, review the approved and discovered lists ('Promote'), and run 'Scan pages now' for a preview (add / remove / keep) before writing. Saving writes the site's own section file #/images.json (created if missing, and an images section in site.json is moved there). The policy that applies is merged from the app's site.json and #/images.json and then the site's.
Shared per folder: several templates and aliases share the same settings — the policy is managed in one place and 'Scan' covers all the templates. URLs generated by client-side JavaScript are not discovered and must be added to allowedSizes manually.
Not subject to sizePolicy: scaleImage and attachFile64 run server-side and are controlled by your own code — only the WxHxM URL is enforced.
Output format: for URL-based scaling, the extension on the seo-name segment (.jpg/.jpeg, .png, .webp, .avif) picks the output format — set it via linkImage's filename argument. Only .webp and .avif depend on images.sizePolicy: under the default "open" policy they fall back to auto, which keeps PNG for PNG sources and produces JPEG for everything else. Set images.sizePolicy to "auto" or "strict" for real WebP/AVIF output. The .jpg/.jpeg and .png extensions work under every policy. See Image output formats (WebP / AVIF).
Scaling modes
Mode | Description |
|---|---|
0 | Scale to fit |
1 | Scale to fill |
2 | No ratio rescale |
3 | Scale with white margin |
4 | Scale with black margin |
5 | No scaling |
See more detailed explanations of each mode below.
Mode names and mode -1 (scaleImage)
In a link — linkImage or a WxHxM URL — the mode is a number from 0 to 5; a negative mode returns HTTP 400. scaleImage also accepts -1 and the mode names below. Names are not case sensitive.
Mode | Name |
|---|---|
-1 | SkipResize (scaleImage only: no resizing) |
0 | ScaleToFit |
1 | ScaleToFill |
2 | Resize |
3 | ScaleAndFill |
4 | ScaleAndFillBlack |
5 | ConvertToJpegNoResize |
Scaling modes explained
>
Scale to fit (0)
The system scales down the image so that it fits within the format defined in the specified width and height parameters. If it is already smaller it keeps it's original size.
Either the width and/or the height is defined
The image does not fill the entire target area if the height/width format in the image does not match
The image is never scaled up if it is too small
A transparent background is kept when the output is PNG, WebP or AVIF; JPEG output gets a white background
Images get the optimal file size
Examples
>
Scale to fill (1)
The system automatically crops the image to fit the format defined in the web pages.
All images end up the same size, and exactly the size defined regardless of the height/width ratio
The whole image is not always included
Cropping may occur - the top/bottom or left/right part of the image can be cut away.
A transparent background is kept when the output is PNG, WebP or AVIF; JPEG output gets a white background
Images may be scaled up if they are too small
Images get the optimal file size
Examples
>
No ratio rescale (2)
Image is rescaled and stretched.
>
Scale with white margin (3)
The system scales the image down so that it fits within the format defined in the web pages, and fills the surrounding area with white so that the image always reaches the target size.
The image fills the entire target area even if the height/width format of the image does not match
The image is not scaled up if it is too small
A transparent background is kept when the output is PNG, WebP or AVIF; JPEG output gets a white background
Images get the optimal file size
The image may be padded with edges above or below if the size format does not match the target area — white for JPEG, transparent for PNG, WebP and AVIF
Examples
>
Scale with black margin (4)
Same as the previous mode, but with black margins.
Examples
>
No scaling (5)
Images are used at the size they were uploaded and are not rescaled.
The image is re-encoded even though the size is kept - the bytes are not identical to the original
If you need the original file unchanged, use linkFile instead of a scaling URL
The browser may scale the images itself if it is defined in CSS
Images can be unnecessarily large relative to their display size