Image output formats Last updated: 12. Aug 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	Alpha	Use
JPEG	`jpeg`	GDI+ (fastest)	No	Standard, universal. Transparency is flattened, normally onto white.
PNG	`png`	GDI+	Yes	Lossless. Graphics, screenshots and logos.
WebP	`webp`	Magick.NET	Yes	Better compression than JPEG; universal browser support today.
AVIF	`avif`	Magick.NET	Yes	Best compression; modern browsers. Recommended for the highest performance score (Google's recommendation).
Auto	`auto` (default)	—	Follows the source	Uses `images.defaultFormat` when that is set. Without a site default: keeps PNG for PNG sources, JPEG for everything else.

Alpha depends on the source as much as on the target. PNG, WebP and AVIF all carry an alpha channel and the converter preserves an existing one, so a transparent PNG requested as .webp or .avif comes back transparent. No format can restore transparency that was already flattened, though: a JPEG source converts to WebP or AVIF with its background baked in, because JPEG never had an alpha channel to begin with. When a converted image has an unexpected solid background, look at the source file before you suspect the output format. Note that auto falls through to JPEG for any source it does not preserve, which discards alpha.

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. 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. That requirement is deliberate: "open" means the public WxHxM URL has no size whitelist, so anyone can request arbitrary dimensions, and the Magick.NET formats cost markedly more CPU to encode than JPEG/PNG. Registering your sizes closes that surface — and WebP/AVIF is what you get for doing it. The .jpg/.jpeg and .png extensions work under every policy. 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.