---
title: 'Image Shortcode Basics'
description: 'Render responsive images with Baseline''s image shortcode: alt and caption, multiple formats and sizes, and verify output in dist/media.'
slug: 'image-shortcode-basics'
type: 'article'
date: 2026-04-13T00:00:00.000Z
lang: 'en'
url: 'https://www.eleventy-baseline.dev/docs/feature-guide/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 {% raw %}`{% image %}`{% endraw %} syntax.

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:
  ```bash
  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`:

{% raw %}<!-- raw render-->

```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."
} %}
```

{% endraw %}<!-- end raw render -->

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| image shortcode]] reference for the full option list.

## 3) Run and verify

```bash
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:

```bash
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.
- The shortcode emits site-root-relative paths (`/media/...`). For an absolute image URL, e.g. to set as a page's `ogImage` share card, combine the path with `settings.url` from `_data/settings.js`.
- 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](https://www.11ty.dev/docs/plugins/image/) for configuration.