English  Nederlands  Français  Toggle theme

Eleventy Baseline

Start building your site, skip the recurring setup work.
Table of Contents

Image Shortcode Basics

Render a responsive image with one line of template code. By the end you'll have a <picture> element on the page, a folder of generated formats and widths under dist/media/, and a feel for what the shortcode is doing on your behalf. Baseline's image shortcode is a thin wrapper over Eleventy Image, and it's the only shortcode the plugin ships.

A shortcode is just a template helper Eleventy invokes with {% image %} syntax. Baseline registers it for you the moment you load the plugin.

Although you could place your media directory anywhere you'd like, Baseline's convention is src/media/. If you are used to have them under assets/img/, in Baseline that directory is reserved for global image assets.

What you will build

  • A page rendering a <picture> with avif and webp sources.
  • Multiple widths of the same image emitted to /dist/media/.

Prerequisites

  • Baseline installed and loaded.
  • package.json with "type": "module" and the start/build scripts (as in earlier tutorials).
  • The 11ty Image peer dependency should have been previously installed, if not:
    npm install @11ty/eleventy-img

1) Add a sample image

Place any jpg or png image of your choice at src/media/. Rename it example.{jpg, png} for this tutorial. The format you start from matters less than what you put in alt. note that eleventy-img doesn't upscale your images; if your image is 640px only 320w + 640w of the default widths will be generated.

2) Use the shortcode in a page

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

---
title: 'Image Shortcode Demo'
slug: 'image-demo'
description: 'Responsive image via Baseline shortcode.'
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."
} %}

The shortcode brings a set of defaults so you don't have to think about responsive widths or modern formats unless you want to:

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

Paths are resolved from the project's input directory automatically: a leading-slash path like /media/example.jpg maps to src/media/example.jpg. A fully qualified path works too if that suits the project better.

  • Dot-relative paths (./src/media/example.jpg, ./example.jpg) will not resolve. Stick to a leading slash from src/, like /media/example.jpg.

The defaults cover most pages. Reach into the options when a particular image needs different handling. See the Image shortcode reference for the full option list.

3) Run and verify

npm start
  • Open /image-demo/ and inspect the <picture> and <source> tags.
  • Check /dist/media/ for generated variants (named like example-a1b2c3-768w.avif; the hash is derived from the image content).

4) Production build

Change URL in .env to an absolute URL. On a deployed site that's your real production URL; for this exercise, any absolute URL (e.g. https://www.example.com/) works to verify the output. Then run:

npm run build
  • Recheck /dist/media/ and the rendered HTML in dist/image-demo/index.html.
  • Reset URL in .env to "http://localhost:8080/".

5) Notes

  • Keep alt meaningful. Captions are optional; alt text isn't.
  • Reasonably sized originals are kinder to the build. Very large inputs generate very large outputs.
  • For absolute image URLs (social or OG meta tags through head.meta[]), combine the path with settings.url from _data/settings.js. Canonicals already use it.
  • In dev (when ELEVENTY_RUN_MODE=serve), the shortcode uses Eleventy Image's transformOnRequest mode, which defers image processing to the first browser request and keeps server startup snappy. Builds pre-generate everything as usual. If transformOnRequest fails in dev, the shortcode falls back without it.

Optional: use the Image Transform plugin

Prefer not to call a shortcode at all? Eleventy's Image Transform plugin processes every <img> and <picture> tag it finds. The trade-off is exactly that: it touches everything rather than the images you opt in to. See the Image plugin docs for configuration.