Image output formats Last updated: 21. Jul 2026

Docly can deliver modern image formats (WebP / AVIF) with better compression via scaleImage and the site-wide default format.

Docly can deliver modern image formats with better compression. This applies to scaleImage, attachFile64, URL-based scaling via linkImage (the extension on the display name picks the format, e.g. …/1200x800x0/produkt.webp ⇒ WebP), and the site-wide default (images.defaultFormat in site.json).

Available formats

Format	Value	Encoding	Use
JPEG	`jpeg`	GDI+ (fastest)	Standard, universal.
PNG	`png`	GDI+	Lossless / transparency.
WebP	`webp`	Magick.NET	Better compression than JPEG; universal browser support today.
AVIF	`avif`	Magick.NET	Best compression; modern browsers. Recommended for the highest performance score (Google's recommendation).
Auto	`auto` (default)	—	Preserve the source format (PNG → PNG), otherwise JPEG. Falls back to `images.defaultFormat` if set.

How to choose a format

Per call: docly.scaleImage(bytes, 1200, 800, 0, 80, "webp") — an explicit format always wins. quality (here 80) applies to WebP/AVIF too.
Site default: set images.defaultFormat: "webp" in site.json → every scaleImage call without an explicit format uses WebP.

// explicit AVIF, quality 60
var out = docly.scaleImage(bytes, 800, 600, 0, 60, "avif");

// or a site-wide default in site.json:
{ "images": { "defaultFormat": "webp" } }

Quality goes with the format. The three lossy formats do not share a scale, so one number for all of them is rarely right: WebP at 90 can produce a file larger than a well-optimised source, and AVIF at 50 already looks like JPEG at 85. Docly therefore defaults to JPEG 85, WebP 78, AVIF 50, and you can override them per format in site.json:

{ "images": { "defaultFormat": "webp", "quality": { "webp": 78, "avif": 50 } } }

This one setting covers both URL-based scaling (and therefore linkImage) and every scaleImage call that does not pass a quality of its own. Quality can never be set from a URL. See Quality in the site.json reference for the lookup order and the cache caveat.

URL-based scaling now supports WebP/AVIF too. The output format of a URL like /photo.jpg/WxHxM/seo-name.ext is chosen from the extension on the display name (seo-name.ext): .jpg/.jpeg, .png, .webp and .avif each steer the conversion; .gif/.svg are not converted. Use linkImage with a filename argument to set it. This requires images.sizePolicy: "auto" or "strict" — the default "open" policy does not support WebP/AVIF and serves such a link as JPEG regardless of the extension. Note: there is no Accept-header negotiation and no ?format= — an .avif link is delivered to everyone, so AVIF must sit inside a <picture> with a WebP/JPEG fallback (see Adopt AVIF and WebP image formats). scaleImage / attachFile64 remain available for generating and storing images server-side. See Image scaling & allowed sizes.