Eleventy Plugin Baseline

A magic carpet ride

Table of Contents

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).