Images

Every image a template prints goes through named transforms: a shape (an aspect ratio and a fit), a ladder of widths, a list of formats and a default sizes. You declare the transforms once in config/images.yaml, and a template asks for one by name. The engine writes the srcset, sizes, width, height, alt and loading attributes, generates each derivative the first time it is requested, and never upscales.

A minimal exampleCopy Anchor Link

# config/images.yaml
breakpoints:
  md: 48rem
  lg: 64rem

transforms:
  card:
    aspect: "3:2"
    widths: { min: 320, max: 1200 }
    sizes: "lg:33vw md:50vw 100vw"
  hero:
    aspect: "16:9"
    widths: { min: 640, max: 2560 }
    sizes: "100vw"

{# templates/_shared/article/entry.html #}
{% if article.heroImage %}
  {{ article.heroImage.figure("hero", priority=true, class="article__hero") }}
{% endif %}

{% for related in article.related %}
  {% if related.heroImage %}{{ related.heroImage.img("card") }}{% endif %}
{% endfor %}

figure("hero", priority=true) prints a <figure> holding a <picture> with a <source> per format, the <img> with its whole srcset, and the caption and credit in a <figcaption>. Because it is the page’s main image, it loads eagerly with fetchpriority="high", and the engine adds a preload for it to the <head>.

Run engine-dmo media transforms to see each transform resolved, with its ladder of widths and the formats this build serves.

Where image values come fromCopy Anchor Link

An image value is what each of these gives a template:

An empty asset field is false, and its methods print nothing, so {% if entry.heroImage %} is only needed when you wrap the image in markup of your own. Printing the value itself, {{ entry.heroImage }}, prints the original file’s URL.

The field’s own configuration (which kinds of file an editor may choose, minimum dimensions, required alt text, per-use focal points and captions) is described in the asset field.

MethodsCopy Anchor Link

Options of img, picture and figureCopy Anchor Link

Any other keyword becomes an attribute of the <img> (of the <figure>’s image for figure). Keywords may contain hyphens:

{{ entry.heroImage.picture("card", class="card__img", data-role="lead", aria-describedby="credit") }}

class is merged with the engine’s own classes. src, srcset, width, height and style belong to the helper and are refused, as are inline event handlers (onload=). A keyword one or two letters away from an option (sizez=) is reported as a misspelling.

The url methodCopy Anchor Link

<link rel="preload" as="image" href="{{ entry.heroImage.url('hero', width=1600) }}">
<meta property="og:image" content="{{ entry.heroImage.url('social', absolute=true) }}">

You rarely need the second line: head() writes the Open Graph image itself.

The transform objectCopy Anchor Link

transform(name, width=) returns the parts, for an <img> you write yourself:

{% set t = entry.heroImage.transform("card") %}
<img {{ t.attributes(class="card__img") }} alt="{{ entry.heroImage.alt }}">

Prefer attributes(). A variable printed into src or srcset by hand must go through the url filter, and engine-dmo check warns about a hand-built <img> whose srcset has width descriptors and no sizes.

PropertiesCopy Anchor Link

When the alt text or caption came from a fallback locale, img, picture and figure write it with a lang attribute, so a screen reader pronounces it correctly.

CreditsCopy Anchor Link

An image whose licence requires a credit (creditRequired) must show it. figure() always writes the credit. When you print an image with img() or picture(), engine-dmo check warns unless the same template prints the image’s credit:

{{ entry.heroImage.img("card") }}
{% if entry.heroImage.credit %}<p class="credit">{{ entry.heroImage.credit }}</p>{% endif %}

config/images.yamlCopy Anchor Link

The install’s breakpoints, defaults and transforms. Without the file there are no transforms, and every image method needs one. A site may add or replace transforms in config/sites/<key>/images.yaml.

# config/images.yaml
breakpoints:                 # named min-widths, used by sizes shorthands and art direction
  md: 48rem
  lg: 64rem

defaults:
  formats: [avif, webp, jpeg]               # sources in this order; JPEG is the <img> fallback
  quality: { avif: 55, webp: 75, jpeg: 80 }
  widths: { min: 320, max: 2560, ratio: 1.25 }
  density: 2
  placeholder: dominant

transforms:
  thumb:
    width: 200                              # a fixed display width: 1x and 2x
    aspect: "1:1"
  card:
    aspect: "3:2"
    widths: { min: 320, max: 1200 }
    sizes: "lg:33vw md:50vw 100vw"
  hero:
    aspect: "16:9"
    widths: { min: 640, max: 2560 }
    sizes: "100vw"
  square:
    aspect: "1:1"
    widths: [480, 800, 1200]                # an explicit ladder
  hero-art:                                 # art direction: a square crop on narrow screens
    sources:
      - { below: md, transform: square }
      - { transform: hero }
  logo:
    width: 200
    fit: contain
    background: transparent
  social:
    width: 1200
    aspect: "1.91:1"
    formats: [jpeg]

breakpointsCopy Anchor Link

A map of name to a positive CSS length in rem, em or px. Each is a min-width. from: lg in an art-direction source means (min-width: 64rem); below: md means (max-width: 47.99rem) (0.02 under for px).

defaultsCopy Anchor Link

density and placeholder are defaults only; a transform cannot set them.

A transformCopy Anchor Link

A transform has exactly one of width, widths (a list) or a range (widths: { ... }, else the default range). Widths are between 16 and 8,192 pixels. Names are lower-case letters, digits, hyphens and underscores; names starting with an underscore are reserved for the engine’s own transforms.

The width ladderCopy Anchor Link

• A range generates widths from min to max, each ratio times the last, rounded to a multiple of 8. A step within half a step of max is dropped in favour of max.
• A list is used as written.
• Nothing is upscaled. Widths above the widest box the source can fill are dropped, and that width joins the ladder as its top step, so a 1,000 pixel photograph in a 2,560 ladder serves at most 1,000 pixels.
• A fixed-width transform serves its width at 1x, 2x and so on up to density.

engine-dmo media transforms --source-width 1000 shows each ladder for a source of that width.

The sizes shorthandCopy Anchor Link

"lg:33vw md:50vw 100vw" names breakpoints from the largest down and ends with the default. It expands to (min-width: 64rem) 33vw, (min-width: 48rem) 50vw, 100vw. A string that is already a full media list is used as written. sizes="auto" on a lazy image writes sizes="auto, <the transform's sizes>", which browsers that support it size from the layout.

Art directionCopy Anchor Link

A transform with sources renders a different crop per breakpoint:

transforms:
  hero-art:
    sources:
      - { below: md, transform: square }
      - { transform: hero }

picture("hero-art") prints a <source media="(max-width: 47.99rem)"> per format with the square crop, then the hero crop as the <img>. Only the last source may have no breakpoint; a source may not name another art-direction transform or the same breakpoint twice. With priority=true, the preload is the <img>’s own crop.

Per-site transformsCopy Anchor Link

# config/sites/town/images.yaml
transforms:
  card:
    aspect: "4:3"
    widths: { min: 320, max: 1200 }
    sizes: "lg:33vw md:50vw 100vw"

A site’s transform replaces the install’s transform of the same name whole, not key by key: restate every key you need. Breakpoints and defaults are the install’s.

What check reportsCopy Anchor Link

engine-dmo check reports every problem in images.yaml together, each at its line and column: an unknown key, a breakpoint that is not a length, a breakpoint used and not declared, a ratio at or below 1, a min above max, an aspect that does not parse, an art-direction source naming an unknown transform or a breakpoint twice, a reserved name, and a transform whose largest output exceeds media.max_pixels. In templates it reports a literal transform name or sizes breakpoint that the site does not define (with a “did you mean”), an attribute the helper owns, an unknown keyword, and a second priority=true on the same page as a warning.

Formats and the build you runCopy Anchor Link

What a build can encode depends on its image processor. The image pipeline line of engine-dmo version names it and what it encodes:

The note reads note: the image transforms name avif and webp, which this build cannot encode; it serves the rest, and the vips image serves all of them. It is not a warning and changes nothing: the page serves JPEG and PNG. A transform without formats inherits the default [avif, webp, jpeg], so every such transform names AVIF and WebP. To silence the note on a build that will only ever serve JPEG, set defaults: { formats: [jpeg] } (or formats: [jpeg] on each transform); leave the default if production runs the -vips image.

An SVG asset is never rasterised: its methods serve the original with no srcset or sources.

PlaceholdersCopy Anchor Link

dominant sets the image’s background colour to its dominant colour; blur sets a 16 pixel blurred preview as the background image. Both are written as a style attribute by the engine, so a content security policy must allow inline style attributes (style_src_attr: ["'unsafe-inline'"]) for them to show. Templates themselves can never write a style attribute. none writes nothing.

Theme imagesCopy Anchor Link

Images that belong to the design rather than to content (a team photograph, a background illustration) live under public/ and go through the same pipeline:

{% set team = images.file("img/team.jpg") %}
{{ team.figure("card", alt=t("about.team_alt")) }}

images.file(path) reads a file under the project’s public/ directory (refusing a path that leaves it) and returns an image value with every method above. It has no alt text of its own, so pass alt=. Its derivatives are cached by the file’s content hash.

images.breakpoints lists the breakpoints (name, value, from, below) and images.transforms the site’s transforms (name, aspect, fit, sizes, formats, width or widths, artDirected), for a template that needs them.

How derivatives are made and servedCopy Anchor Link

• A derivative is generated the first time it is requested, once even under concurrent requests and across replicas, then stored. If generation fails, the request is redirected to the original (not cached), and the next request tries again.
• Its address is named by what it is (the asset, its version, its framing and the transform’s resolved definition), not by the transform’s name. Renaming a transform reuses every derivative; changing one produces new addresses on the next render, with no purge.
• Derivatives and originals are served with Cache-Control: public, max-age=31536000, immutable.
• Publishing a document renders its pages and generates the derivatives they reference in the background. engine-dmo media warm does the same on demand, and engine-dmo warm --media queues it for every published page after a deploy.
• Derivatives not served for media.derivatives.keep_unused (90 days by default) are pruned nightly; engine-dmo media prune runs it by hand.

Checking what a page downloadsCopy Anchor Link

• engine-dmo render <path> --json adds an images report: each image on the page with its transform, the sizes written, the ladder, the formats, and each derivative’s bytes and whether it is stored yet. Without --json it prints a short table on standard error. It needs a database (Testing).
• Under engine-dmo serve --dev, a development script compares each image’s drawn width with the candidate the browser chose and reports an image that downloads far more pixels than it shows, with a suggested sizes, in the browser console and in engine-dmo dev status.

RelatedCopy Anchor Link

• The asset field: what editors can choose, alt text and framing.
• Media: the library, uploads, rights and the commands.
• Images configuration reference.