Image Shortcode Basics

Render a responsive image with Baseline’s image shortcode (eleventy-img). You’ll add a source image, call the shortcode with alt/caption, see generated formats, and verify output in /dist/media/. Uses npm, Node 20.15.0+, and the same Baseline setup as earlier tutorials.

What you’ll build

• A page that renders a <picture> with avif/webp/fallback sources.
• Generated images emitted to /dist/media/ with multiple widths.

Prerequisites

• Baseline installed and loaded.
• Install the peer dependency:

  npm install @11ty/eleventy-img

• package.json with "type": "module" and scripts (dev, build) as in earlier tutorials.

1) Add a sample image

Place an image at src/media/example.jpg. JPEG/PNG are fine.

2) Use the shortcode in a page

Create src/content/pages/image-demo.md:

---
title: "Image Shortcode Demo"
description: "Responsive image via Baseline shortcode"
permalink: "/image-demo/"
layout: "layouts/base.njk"
---

This page displays an image using the {% raw %}`{% image {} %}`{% endraw %} shortcode.

{% image {
  src: "/media/example.jpg",
  alt: "A descriptive alt text for accessibility",
  caption: "Example image rendered responsively with the image shortcode."
} %}

Defaults (from the shortcode):

• Widths: [320, 640, 960, 1280]
• Formats: ["avif", "webp", "jpeg"]
• Output: ./dist/media/, URL: /media/
• Sizes: "(max-width: 768px) 100vw, 768px"
• loading: "lazy", decoding auto-set, and a <figure> if caption is provided; width/height set by default.

The shortcode resolves the input directory automatically: a leading-slash path like /media/example.jpg maps to src/media/example.jpg. You can still pass a fully qualified path if you prefer.

• Dot-relative paths like ./src/media/example.jpg or ./example.jpg won’t resolve; use a leading slash from src/ (e.g., /media/example.jpg).

3) Optional tweaks

• Control sizes: sizes: "(max-width: 768px) 100vw, 768px"
• Change widths/formats: widths: [320, 640, 960, 1280], formats: ["avif", "webp", "jpeg"]
• Classes: containerClass (on <picture>), imageClass (on <img>)
• Figure/attrs: set caption (or figure: false) to control the figure wrapper; attrs.class merges with imageClass; style is supported (alias of attrs.style)
• Dimensions: set setDimensions: false to omit width/height
• Output: override outputDir and urlPath if you need a different media location
• Eager load: loading: "eager" (decoding switches to sync)
• Common options (cheat sheet):
  • src (required), alt (recommended), caption (optional)
  • widths (array of numbers), formats (e.g., ["avif","webp","jpeg"]), sizes
  • loading ("lazy"/"eager"), containerClass, imageClass, figure, setDimensions, style
  • outputDir, urlPath, attrs (merges class with imageClass; style allowed)

4) Run and verify

npx rimraf dist/ && npm run dev

• Open /image-demo/ and inspect the <picture> and <source> tags.
• Check /dist/media/ for generated variants (named like example-768w.avif, etc.).

5) Production build

npx rimraf dist/ && npm run build

• Recheck /dist/media/ and the rendered HTML in dist/image-demo/index.html.

6) Notes

• Keep alt meaningful; captions are optional.
• Use reasonably sized originals; very large inputs generate large outputs.
• For social/OG tags, set absolute image URLs (combine with your site.url in _data/site.js); canonicals already use site.url.
• The shortcode runs transformOnRequest when ELEVENTY_RUN_MODE=serve (dev); builds still pre-generate assets. Dev can feel slower while images are rendered on demand.

7) Optional: use the Image Transform plugin

If you prefer not to call the shortcode, you can add Eleventy’s Image Transform plugin to process all <img>/<picture> tags automatically. See the official Image plugin docs for configuration and trade-offs (e.g., transforms every image it finds, rather than opt-in shortcode usage).