Table of Contents

Image shortcode

The shortcode is Baseline's; the underlying engine is @11ty/eleventy-img. The two halves split cleanly:

Baseline owns the shortcode call signature ({% image { src, alt, ... } %}), the default widths and format order, the filename convention, the on-request optimisation in dev, the <picture> and <figure> HTML assembly, and the cohabitation rule with eleventyImageTransformPlugin.
eleventy-img owns the actual image transcoding, format conversion, content-hash digest, srcset emission, and remote-image fetching.

Anything you can configure on @11ty/eleventy-img directly, you can pass through the shortcode's options. Anything that is purely about the rendered HTML or the conventions Baseline applies on top is owned here.

Usage

{% image {
	src: "/media/mountains.jpg",
	alt: "Mountains at sunset",
	caption: "Responsive image via baseline",
	widths: [320, 640, 960],
	formats: ["avif", "webp", "jpeg"]
} %}

What it does

Generates multiple formats and widths and returns a <picture> containing one <source> per format and a single <img> fallback. Wraps in <figure> when a caption is provided.
Uses on-request transforms during ELEVENTY_RUN_MODE=serve (via eleventy-img's transformOnRequest) to keep dev startup quick. If that fails, retries without the flag and logs a warning. In build mode, errors throw immediately.
Adds the eleventy:ignore attribute on <img> when eleventyImageTransformPlugin is registered, so the transform plugin doesn't reprocess the shortcode's output. Both can coexist in the same project; the shortcode owns explicit calls, the transform plugin owns content-level rewrites.

The Image shortcode Shape

{% image {
	src: "/media/example.jpg",
	alt: "Description",
	caption: "",
	loading: "lazy",
	containerClass: "",
	imageClass: "",
	widths: [320, 640, 960, 1280, 1920, "auto"],
	sizes: "(max-width: 768px) 100vw, 768px",
	formats: ["avif", "webp"],
	outputDir: "./dist/media/",
	urlPath: "/media/",
	attrs: {},
	style: "",
	figure: true,
	setDimensions: true
} %}

Every key shown with its default. src and alt are required; the rest are optional.

Required arguments

src - local path or remote URL. Throws if missing. Local paths are resolved against eleventyConfig.directories.input.
alt - required. A missing alt logs a warning but does not break the build. Use an empty string (alt: "") for purely decorative images.

Defaults

Widths: [320, 640, 960, 1280, 1920, 'auto']
Formats: ['avif', 'webp'] (order matters; the first format becomes the <img> fallback's source)
Sizes: '(max-width: 768px) 100vw, 768px'
Output: urlPath: '/media/', outputDir derived from Eleventy's output directory (e.g. ./dist/media/)
Filename: name-hash-widthw.format (e.g. hero-a1b2c3-640w.avif). The hash is the first six characters of eleventy-img's content digest, so different sources sharing a basename do not collide.
Caption: off unless caption is set; when set, wraps in <figure>.
Dimensions: width and height are written onto <img> unless setDimensions: false.

Common options

caption, loading ('lazy' or 'eager'), containerClass, imageClass
widths, formats, sizes
outputDir, urlPath
attrs - extra attributes on <img>. The class key merges with imageClass; everything else passes through. attrs.style takes precedence over the top-level style argument.
style - inline style on <img>. Convenience for the common case; use attrs.style if you also need to override.
figure (default true) - only takes effect when caption is also set.
setDimensions (default true) - set to false to omit width/height on the <img>.

Notes

Generated URLs are site-root-relative (/media/...). Keep settings.url set if you need absolute URLs for canonical tags or OpenGraph metadata; the shortcode itself does not prefix output paths with the site URL.
If you also use eleventyImageTransformPlugin, the shortcode adds eleventy:ignore on its own <img> so the transform doesn't reprocess it. Use whichever fits the page: the shortcode for explicit calls with control over widths/formats, the transform for rewriting <img> tags written into Markdown.
The dev-mode transformOnRequest retry is unguarded. If the second attempt also fails (bad src, missing file), the error surfaces. The warning blames transformOnRequest either way; the underlying cause may be elsewhere.