Image shortcode

Baseline ships an image shortcode that wraps @11ty/eleventy-img to generate responsive <picture> markup.

What it does

• Generates multiple formats and widths, returns <picture> + <img>; wraps in <figure> when a caption is provided.
• Uses on-request transforms during ELEVENTY_RUN_MODE=serve (via transformOnRequest) to speed up dev startup. If it fails, retries without it. In build mode, errors throw immediately.
• Adds eleventy:ignore when eleventyImageTransformPlugin is present to avoid double-processing. This means you can use both the shortcode and the Image Transform plugin in the same project — the shortcode's output won't be rewritten by the transform.

Required

• src — local path or remote URL. Throws an error if missing.
• alt — strongly recommended. A missing alt logs a warning but doesn't break the build. Use an empty string for decorative images.

Defaults

• Widths: 320, 640, 960, 1280, 1920, 'auto'
• Formats: avif, webp (order matters)
• Sizes: (max-width: 768px) 100vw, 768px
• Output: urlPath: "/media/", outputDir derived from Eleventy's output directory (e.g. ./dist/media/)
• Filenames: name-hash-widthw.format (e.g. hero-a1b2c3-640w.avif). The hash is a 6-character content digest that prevents collisions when different source images share a filename.
• Caption off unless caption is set; when set, wraps in <figure>.
• Adds width/height unless setDimensions: false.

Common options

• caption, loading (lazy/eager), containerClass, imageClass
• widths, formats, sizes
• outputDir, urlPath
• attrs: extra attributes on <img>; class merges with imageClass
• style: inline style on <img>. Separate from attrs.style — if both are passed, attrs.style takes precedence.
• figure (default true), setDimensions — figure only has an effect when caption is also set.

Usage

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

Notes

• Keep site.url set so generated URLs are correct when published.
• If you use the HTML Image Transform plugin, Baseline still provides the shortcode; the transform focuses on rewriting existing <img> in content. Use whichever fits the page.