Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tannerdolby/eleventy-plugin-sharp-respimg

Eleventy plugin which performs build-time image transformations and generates responsive image markup.
https://github.com/tannerdolby/eleventy-plugin-sharp-respimg

11ty-plugin eleventy image-transformations

Last synced: about 1 month ago
JSON representation

Eleventy plugin which performs build-time image transformations and generates responsive image markup.

Awesome Lists containing this project

README 

        
# eleventy-plugin-sharp-respimg

An Eleventy [shortcode](https://www.11ty.dev/docs/shortcodes/#paired-shortcodes) that performs build-time image transformations with [Sharp](https://www.npmjs.com/package/sharp) to resize large images into `.jpeg` and `.webp` formats with varying dimensions and generates `` tags for responsive images.



🚨 Phasing out this plugin as I'm no longer actively maintaining it. Advising migration to the official 11ty plugin [@11ty/eleventy-img](https://www.11ty.dev/docs/plugins/image/)



## Installation

In your Eleventy project, [install the plugin](https://www.npmjs.com/package/eleventy-plugin-sharp-respimg) from npm:

```

npm install eleventy-plugin-sharp-respimg

```

Then add it to your [Eleventy Config](https://www.11ty.dev/docs/config/) file:

```js

const respimg = require("eleventy-plugin-sharp-respimg");



module.exports = (eleventyConfig) => {

    eleventyConfig.addPlugin(respimg);

}

```



## What does it do?

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

 

    

    Photo of a car



```

- 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](https://www.smashingmagazine.com/2014/05/responsive-images-done-right-guide-picture-srcset/), 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:



```nunjucks

---

src: yellow-modern.png

alt: Some alt text

inputDir: ./src

imgDir: /images/

widths: 

    - 320

    - 640

    - 1024

sizes: "(max-width: 450px) 33.3vw, 100vw"

className: test-class

width: 1024

height: 768

---

{% respimg

    src=src,

    alt=alt,

    inputDir=inputDir,

    imgDir=imgDir,

    widths=widths,

    sizes=sizes,

    className=class,

    width=width,

    height=height

%}

```



Or in a one liner by defining an object with the required properties:



```nunjucks

---

data:

    src: yellow-modern.png

    alt: Some alt text

    inputDir: ./src

    imgDir: /images/

    widths: 

        - 320

        - 640

        - 1024

    sizes: "(max-width: 450px) 33.3vw, 100vw"

    className: test-class

    width: 1024

    height: 768

---



{% respimg data %}

```



### Using the paired shortcode more than once for the same image

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](https://www.11ty.dev/docs/data-global/) or [front matter](https://www.11ty.dev/docs/data-frontmatter/) 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 %}

```



## Paired shortcode options



| Parameter | Type | Description |

| ----------| -----|-------------|

| src       | `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.



Recommended fallback `` boilerplate CSS:

```css

.my-image {

    max-width: 100%;

    object-fit: cover;

    height: auto;

    margin: 0 auto;

}

```



## Maintainers

[@tannerdolby](https://github.com/tannerdolby)



## Other Responsive Image Plugins

- Official 11ty Image plugin: [@11ty/eleventy-img](https://github.com/11ty/eleventy-img)

- [eleventy-respimg](https://github.com/eeeps/eleventy-respimg)