GuideAdd content to your site
Images
Responsive images with the image tag, the image_url and image_size filters, and the images, image-map and pictures steps for Markdown images.
Douze resizes and converts images at build time with libvips, and writes the markup that
goes with them: <picture>, srcset, width and height. You can do this in two ways. The image tag works in
any template. Three workflow steps do the same for the plain  images of Markdown pages. This page covers
both, the filters, light and dark images, and what libvips is needed for.
The image tagLink to this heading
{% image "images/dashboard.png", alt: "The dashboard", widths: [640, 1280], formats: ["webp", "png"], sizes: "(min-width: 60em) 50vw, 100vw", class: "figure" %}
<picture>
<source type="image/webp" srcset="/assets/images/dashboard-640.65ca7992.webp 640w, /assets/images/dashboard-1280.0b5361a5.webp 1280w" sizes="(min-width: 60em) 50vw, 100vw">
<img src="/assets/images/dashboard-1280.ee42001a.png" srcset="/assets/images/dashboard-640.f66c56a9.png 640w, /assets/images/dashboard-1280.ee42001a.png 1280w" sizes="(min-width: 60em) 50vw, 100vw" width="1280" height="720" alt="The dashboard" class="figure" loading="lazy" decoding="async">
</picture>
- The source is relative to the page's folder, or to the content folder when it starts with
/. It is a dependency of the page: changing the image renders the page again. - There is a
<source>per format but the last, and an<img>of the last format at its largest width. One format gives a plain<img>, with asrcsetwhen there are several widths. - Each variant is written to
/assets/images/(output) as<name>-<width>.<hash>.<ext>. The hash is the variant's, so a changed image gets new urls and can be cached forever. A variant that several pages use is written once. - Variants are never wider than the source. EXIF, XMP and ICC metadata are stripped.
widthandheightare always set, so the page does not shift while images load.loadingislazyanddecodingisasyncunless you set them.- Any other named argument is an attribute (
data-zoom: truewritesdata-zoom).
Arguments take strings, numbers, true, false, lists and variables (page.hero). formats are webp, avif,
png and jpeg, and quality defaults to 80.
DefaultsLink to this heading
widths, formats, quality, output and loading default to the images settings of the markdown section,
so a site sets them once:
markdown:
images:
widths: [640, 1280]
formats: [webp]
quality: 80
output: assets/images
loading: lazy
Without widths, a variant has the source's width, and without formats, the source's format.
Light and dark imagesLink to this heading
{% image light: "images/flow-light.png", dark: "images/flow-dark.png", alt: "The flow" %}
This gives one <picture> whose dark sources have media="(prefers-color-scheme: dark)". A site that toggles a
theme attribute instead uses theme: "attribute": the tag writes two elements, with data-theme="light" and
data-theme="dark", and the site's CSS hides one.
SVG and GIFLink to this heading
An SVG or a GIF is copied as it is, fingerprinted (arch.ca50de10.svg), with its size read from the file: an SVG's
width and height, or its viewBox. These need no libvips.
FiltersLink to this heading
<meta property="og:image" content="{{ "images/hero.png" | image_url: width: 1200, format: "jpeg" | absolute_url }}">
{% assign size = "images/hero.png" | image_size %}
<div style="aspect-ratio: {{ size.width }} / {{ size.height }}">
image_url makes one variant and returns its url, for meta tags and CSS. It takes width, format, quality and
output. image_size returns the source's { width, height }.
Markdown imagesLink to this heading
For the images of Markdown pages (), three steps do what the tag does, without a tag:
steps:
pages:
inputs: "_content/**/*.md"
uses: frontmatter
permalink:
needs: pages
uses: permalink
render:
needs: permalink
uses: liquid
markdown:
needs: render
uses: markdown
images:
inputs: "_content/**/*.{png,jpg,jpeg,webp,avif,gif,svg}"
uses: images
with:
widths: [640, 1280]
formats: [webp, png]
image-map:
needs: images
uses: image-map
pictures:
needs: [markdown, image-map]
uses: pictures
layout:
needs: pictures
uses: layout
write:
needs: [layout, images]
uses: write
imagesreplaces each image file with its variants and a fingerprinted copy of the original, each with animagevalue:{ source, url, width, height, format, variants: [{ url, width, height, format }] }.image-mapcollects them asimages, by source url.picturesrewrites each<img>whose image it knows into a<picture>, as the tag does, and keeps the other attributes (title).
write needs images so that the variants are written. A page depends on the images it shows only.
images is site data for the steps after image-map. A layout, which runs after it, can read it:
{% assign hero = images["/docs/images/hero.png"] %}
<meta property="og:image" content="{{ hero.url | absolute_url }}">
The render step of this workflow runs before image-map, so the Liquid of a page does not see images.
libvipsLink to this heading
Image processing uses libvips through NetVips. The native builds of Douze include it, next to the douze executable.
Without it:
- a workflow with an
imagesorsocial-imagestep fails before building, and says how to get libvips; - the
imagetag and theimage_urlandimage_sizefilters fail only the pages that use them on an image other than an SVG or a GIF.
douze doctor checks it:
STEP REQUIREMENT STATUS DETAILS
images libvips ok 8.18.7