An Eleventy shortcode that performs build-time image transformations with Sharp to resize large images into .jpeg and .webp formats with varying dimensions and generates tags for responsive images.
Installation
In your Eleventy project, install the plugin from npm: `` npm install eleventy-plugin-sharp-respimg ` Then add it to your Eleventy Config file: `js const respimg = require("eleventy-plugin-sharp-respimg");
It turns paired shortcodes like this:`js {% respimg src="car.png", alt="Photo of a car", inputDir="./src", imgDir="/images/", widths=[320, 640, 1024], sizes="(max-width: 450px) 33.3vw, 100vw", className="my-image", width=1024, height=768 %} ` into responsive image markup using tags like this: `html type="image/webp" srcSet="/images/car-320.webp 320w, /images/car-640.webp 640w, /images/car-1024.webp 1024w" sizes="(max-width: 450px) 33.3vw, 100vw" > srcSet="/images/car-320.jpeg 320w, /images/car-640.jpeg 640w, /images/car-1024.jpeg 1024w" sizes="(max-width: 450px) 33.3vw, 100vw" src="car-320.jpeg" alt="Photo of a car" loading="lazy" class="my-image" width="1024" height="768" >
` - The images are responsive by using a element which contains zero or more elements and one element to offer alternative versions of an image for different display/device scenarios. - Using srcset and sizes, you can deliver variable-resolution images, which respond to variable layout widths and screen densities.
Usage Options
Supply the values as name-value pairs to the shortcode like shown in the example above.
You can also use global data or front matter to supply values to the shortcode like this:
If you have already used the utility to transform an image and you call respimg within your code again for the same file, it will generate the responsive image markup using for that image and generate new images if the shortcode parameters change.
Transform mulitple images
The real power of using this paired shortcode is the ability to use data from global data files or front matter to transform multiple images at once.
If you have global JSON data stored in
data.json or in front matter which is an array of objects like this:`json [ { "src": "car.png", "alt": "Photo of a car", "inputDir": "./src", "imgDir": "/images/", "widths": [320, 640, 1024], "sizes": "(min-width: 450px) 33.3vw, 100vw", "class": "my-image", "width": 1024, "height": 768 }, { "src": "flower.png", "alt": "Photo of a flower", "imgDir": "./images/", "widths": [320, 480, 640, 1024], "sizes": "(max-width: 450px) 33.3vw, 100vw", "class": "my-image", "width": 1024, "height": 768 } ] ` you can use the paired shortcode to transform multiple images with varying dimensions into responsive image markup using a for loop like this:`js {% for image in data %} {% respimg src=image.src, alt=image.alt, inputDir="./src", imgDir=image.imgDir, widths=image.widths, sizes=image.sizes, className=image.class, width=image.width, height=image.height %} {% endfor %} `
string | The filename for an image. | | alt | string | A text description of the image. | | inputDir | string | The input directory in your Eleventy config file. | | imgDir | string | The directory where the image file is located. Relative to inputDir. | | widths | int[] or string[] | The desired image widths. Supports up to 10 values. Must provide atleast 3 values in ascending order. | | sizes | string | The sizes attribute which defines a set of media conditions. | | id | string | The id attribute for elements inside the generated . Remember id's may only be used once on a page, they must be unique and cannot repeat. | | className | string | Class name for the fallback image. | | width | int | The fallback image width attribute. | | height | int | The fallback image height attribute. | | fallbackSrcWidth | int | Width of the fallback image in the src attribute. | | quality | int | The quality for Sharp to generate images width. (Default: 85) | | overwrite | boolean | Determines if Sharp generates another set of images for a given input. Make sure this is false when serving locally. (Default: false) | debug | boolean | A boolean to include console output of generated image metadata. |
Notes
- Use ./ when declaring the inputDir parameter as Sharp expects this. - Use .addPassthroughCopy to include the images directory in your _site output e.g. eleventyConfig.addPassthroughCopy("./src/images/");. - The and tags generated by the paired shortcode don't have any styling out of the box. But they can be manipulated with a bit of CSS to apply different width or height attributes.