Skip to content

site-guide, images

Add Images

Aiguille Dibona

Images can be added to the src/assets/images folder and then referenced from posts and pages using standard Markdown syntax.

Adding an image

Place the image inside the src/assets/images folder. For larger sites, it can be useful to organize images into subfolders.
For example:

assets/
└── images/
    └── my-image.jpg

Adding a hero image

A hero image can be added to a post or page through the front matter.
Add hero.image and hero.imageAlt to the Front Matter.
For example:

---
title: 'My Post'
metaDesc: 'Post description'
tags:
  - your tag
hero:
  image: '/assets/images/my-hero.jpg'
  imageAlt: 'A description of the hero image'
---

The hero image will be displayed automatically by the site.

Adding an image to a post or page

Use the standard Markdown image syntax:

![Image description](/assets/images/my-image.jpg)

The text inside the square brackets is the image's alternative text (alt). Use a short and descriptive description of the image.
Pietra di Bismantova

Image processing in development

After adding an image, run the development server or build the site again to make sure the image is available at the expected path.
During development, images may take a little longer to appear after being added or changed. This is because the site uses the @11ty/eleventy-img plugin to process and optimize images.
This processing can take a few moments, especially when working with large images.
After adding or changing an image, give the development server a moment to finish processing before checking the result.

Responsive images

Images are automatically processed and optimized by @11ty/eleventy-img.
The image processing configuration generates multiple formats and sizes:

eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
  extensions: "html",
  outputDir: "./dist/assets/images/",
  urlPath: "/assets/images/",
  formats: ["avif", "webp", "jpeg"],
  widths: [150, 500, 900],
  htmlOptions: {
    imgAttributes: {
      loading: "lazy",
      decoding: "async",
    },
  },
});

For each image, the site automatically generates:

  • AVIF, WebP and JPEG versions.
  • 150px, 500px and 900px wide versions.
  • Responsive image markup so the browser can select an appropriate image size.
  • Lazy loading using loading="lazy".
  • Asynchronous image decoding using decoding="async".

This means you only need to add the original image to the src/assets/images folder. The optimized versions are generated automatically when the site is built.
The generated images are placed in:

dist/
└── assets/
    └── images/

You do not need to create the different formats or sizes manually.