{"id":15022949,"url":"https://github.com/tannerdolby/eleventy-plugin-sharp-respimg","last_synced_at":"2025-10-25T00:31:49.665Z","repository":{"id":40659432,"uuid":"317659546","full_name":"tannerdolby/eleventy-plugin-sharp-respimg","owner":"tannerdolby","description":"Eleventy plugin which performs build-time image transformations and generates responsive image markup.","archived":false,"fork":false,"pushed_at":"2024-02-24T21:21:19.000Z","size":780,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-30T00:35:58.794Z","etag":null,"topics":["11ty-plugin","eleventy","image-transformations"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/eleventy-plugin-sharp-respimg","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tannerdolby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-01T20:27:53.000Z","updated_at":"2024-02-24T22:04:20.000Z","dependencies_parsed_at":"2024-09-17T17:15:22.172Z","dependency_job_id":"75117b28-0ba5-45ad-ba7e-65c9bd99ec0c","html_url":"https://github.com/tannerdolby/eleventy-plugin-sharp-respimg","commit_stats":{"total_commits":98,"total_committers":3,"mean_commits":"32.666666666666664","dds":"0.29591836734693877","last_synced_commit":"845fbea93e37151b2316c694dff0675ec39fd9d3"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tannerdolby%2Feleventy-plugin-sharp-respimg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tannerdolby%2Feleventy-plugin-sharp-respimg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tannerdolby%2Feleventy-plugin-sharp-respimg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tannerdolby%2Feleventy-plugin-sharp-respimg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tannerdolby","download_url":"https://codeload.github.com/tannerdolby/eleventy-plugin-sharp-respimg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238053514,"owners_count":19408699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["11ty-plugin","eleventy","image-transformations"],"created_at":"2024-09-24T19:58:34.068Z","updated_at":"2025-10-25T00:31:49.295Z","avatar_url":"https://github.com/tannerdolby.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# eleventy-plugin-sharp-respimg\nAn 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 `\u003cpicture\u003e` tags for responsive images.\n\n🚨 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/)\n\n## Installation\nIn your Eleventy project, [install the plugin](https://www.npmjs.com/package/eleventy-plugin-sharp-respimg) from npm:\n```\nnpm install eleventy-plugin-sharp-respimg\n```\nThen add it to your [Eleventy Config](https://www.11ty.dev/docs/config/) file:\n```js\nconst respimg = require(\"eleventy-plugin-sharp-respimg\");\n\nmodule.exports = (eleventyConfig) =\u003e {\n    eleventyConfig.addPlugin(respimg);\n}\n```\n\n## What does it do?\nIt turns paired shortcodes like this:\n\n```js\n{% respimg \n    src=\"car.png\", \n    alt=\"Photo of a car\", \n    inputDir=\"./src\",\n    imgDir=\"/images/\",\n    widths=[320, 640, 1024],\n    sizes=\"(max-width: 450px) 33.3vw, 100vw\",\n    className=\"my-image\",\n    width=1024,\n    height=768\n%}\n```\ninto responsive image markup using `\u003cpicture\u003e` tags like this:\n```html\n \u003cpicture\u003e\n    \u003csource \n        type=\"image/webp\"\n        srcSet=\"/images/car-320.webp 320w,\n                /images/car-640.webp 640w,\n                /images/car-1024.webp 1024w\"\n        sizes=\"(max-width: 450px) 33.3vw, 100vw\"\n    \u003e\n    \u003cimg \n        srcSet=\"/images/car-320.jpeg 320w,\n                /images/car-640.jpeg 640w,\n                /images/car-1024.jpeg 1024w\"\n        sizes=\"(max-width: 450px) 33.3vw, 100vw\"\n        src=\"car-320.jpeg\"\n        alt=\"Photo of a car\"\n        loading=\"lazy\"\n        class=\"my-image\"\n        width=\"1024\"\n        height=\"768\"\n    \u003e\n\u003c/picture\u003e\n```\n- The images are responsive by using a `\u003cpicture\u003e` element which contains zero or more `\u003csource\u003e` elements and one `\u003cimg\u003e` element to offer alternative versions of an image for different display/device scenarios. \n- 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.\n\n## Usage Options\nSupply the values as name-value pairs to the shortcode like shown in the example above. \n\nYou can also use global data or front matter to supply values to the shortcode like this:\n\n```nunjucks\n---\nsrc: yellow-modern.png\nalt: Some alt text\ninputDir: ./src\nimgDir: /images/\nwidths: \n    - 320\n    - 640\n    - 1024\nsizes: \"(max-width: 450px) 33.3vw, 100vw\"\nclassName: test-class\nwidth: 1024\nheight: 768\n---\n{% respimg\n    src=src,\n    alt=alt,\n    inputDir=inputDir,\n    imgDir=imgDir,\n    widths=widths,\n    sizes=sizes,\n    className=class,\n    width=width,\n    height=height\n%}\n```\n\nOr in a one liner by defining an object with the required properties:\n\n```nunjucks\n---\ndata:\n    src: yellow-modern.png\n    alt: Some alt text\n    inputDir: ./src\n    imgDir: /images/\n    widths: \n        - 320\n        - 640\n        - 1024\n    sizes: \"(max-width: 450px) 33.3vw, 100vw\"\n    className: test-class\n    width: 1024\n    height: 768\n---\n\n{% respimg data %}\n```\n\n### Using the paired shortcode more than once for the same image\nIf 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 `\u003cpicture\u003e` for that image and generate new images if the shortcode parameters change. \n\n## Transform mulitple images\nThe 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.\n\nIf you have global JSON data stored in `data.json` or in front matter which is an array of objects like this:\n\n```json\n[\n    {\n        \"src\": \"car.png\",\n        \"alt\": \"Photo of a car\",\n        \"inputDir\": \"./src\",\n        \"imgDir\": \"/images/\",\n        \"widths\": [320, 640, 1024],\n        \"sizes\": \"(min-width: 450px) 33.3vw, 100vw\",\n        \"class\": \"my-image\",\n        \"width\": 1024,\n        \"height\": 768\n    },\n    {\n        \"src\": \"flower.png\",\n        \"alt\": \"Photo of a flower\",\n        \"imgDir\": \"./images/\",\n        \"widths\": [320, 480, 640, 1024],\n        \"sizes\": \"(max-width: 450px) 33.3vw, 100vw\",\n        \"class\": \"my-image\",\n        \"width\": 1024,\n        \"height\": 768\n    }\n]\n```\nyou can use the paired shortcode to transform multiple images with varying dimensions into responsive image markup using a `for` loop like this:\n\n```js\n{% for image in data %}\n    {% respimg \n        src=image.src, \n        alt=image.alt, \n        inputDir=\"./src\",\n        imgDir=image.imgDir,\n        widths=image.widths, \n        sizes=image.sizes,\n        className=image.class,\n        width=image.width,\n        height=image.height\n    %}\n{% endfor %}\n```\n\n## Paired shortcode options\n\n| Parameter | Type | Description |\n| ----------| -----|-------------|\n| src       | `string` | The filename for an image. |\n| alt       | `string` | A text description of the image. |\n| inputDir  | `string` | The `input` directory in your Eleventy config file. |\n| imgDir    | `string` | The directory where the image file is located. Relative to `inputDir`. |\n| widths    | `int[]` or `string[]` | The desired image widths. Supports up to 10 values. Must provide atleast 3 values in ascending order. |\n| sizes     | `string` | The `sizes` attribute which defines a set of media conditions. |\n| id | `string` | The `id` attribute for `\u003cimg\u003e` elements inside the generated `\u003cpicture\u003e`. Remember `id`'s may only be used once on a page, they must be unique and cannot repeat. |\n| className     | `string` | Class name for the fallback image.   |\n| width     | `int` | The fallback image `width` attribute.  |\n| height    | `int` | The fallback image `height` attribute. |\n| fallbackSrcWidth | `int` | Width of the fallback image in the `src` attribute. |\n| quality   | `int` | The quality for Sharp to generate images width. (Default: 85) |\n| overwrite | `boolean` | Determines if Sharp generates another set of images for a given input. Make sure this is `false` when serving locally. (Default: false)\n| debug | `boolean` | A boolean to include console output of generated image metadata. |\n\n## Notes\n- Use `./` when declaring the `inputDir` parameter as Sharp expects this.\n- Use `.addPassthroughCopy` to include the images directory in your `_site` output e.g. `eleventyConfig.addPassthroughCopy(\"./src/images/\");`.\n- The `\u003cpicture\u003e` and `\u003cimg\u003e` 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.\n\nRecommended fallback `\u003cimg\u003e` boilerplate CSS:\n```css\n.my-image {\n    max-width: 100%;\n    object-fit: cover;\n    height: auto;\n    margin: 0 auto;\n}\n```\n\n## Maintainers\n[@tannerdolby](https://github.com/tannerdolby)\n\n## Other Responsive Image Plugins\n- Official 11ty Image plugin: [@11ty/eleventy-img](https://github.com/11ty/eleventy-img)\n- [eleventy-respimg](https://github.com/eeeps/eleventy-respimg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftannerdolby%2Feleventy-plugin-sharp-respimg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftannerdolby%2Feleventy-plugin-sharp-respimg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftannerdolby%2Feleventy-plugin-sharp-respimg/lists"}