metalsmith-srcset v1.0.1

metalsmith-srcset

A metalsmith plugin for creating many different types of images from a single image and updating all of the <img> tag srcset attributes with these multiple images.

This plugin converts images to many different sizes and sets the srcset attribute to the newly created. Since many modern browsers are able to interpret the srcset attribute, the browser can choose whichever image size it thinks is best. Under the hood, this plugin uses jsdom to search through all of the <img> elements, gets the image in the src attribute, checks if that image exists in the Metalsmith files, and if it does it converts that image into many different many different sizes for that given image format, and adding a srcset attribute with all of the different images created by the plugin. If dependencies needed to run this plugin are not installed (ImageMagick and GIMP), then those image conversions will be skipped.

As an example, if you have this <img> tag and the image is 300 pixels wide:

<img src="coffee.png" alt="coffee">

After running this plugin, multiple image formats and sizes will be created, and this tag will be replaced with:

<img src="coffee.png" alt="coffee" srcset="coffee-201.png 201w,coffee-135.png 135w">>

NOTE: this plugin will take a long time, often multiple minutes, to convert all of the images. For best usage of this plugin, only run it when your final site is ready to be built. See the metalsmith-if or metalsmith-select plugins to set conditional plugins.

Installation

npm install metalsmith-srcset

Usage

To use this plugin, simply add it to the existing plugins in your Metalsmith source file or include it in the Metalsmith JSON file:

JavaScript

const Metalsmith = require('metalsmith');
const srcset = require('metalsmith-srcset');

Metalsmith(__dirname)
  .use(srcset())
  .build((err, files) => {
    if (err) { throw err; }
  });

JSON

{
  "plugins": {
    "metalsmith-srcset": {}
  }
}

Options

You can pass options to metalsmith-srcset with the Javascript API or CLI. The options are:

• pattern: optional. Only files that match this pattern will be processed. Accepts a string or an array of strings. The default is **/*.html.
• minWidth: optional. The width at which point no more image sizes will be created for a given image type. For example, if the minWidth is 100, then no images will be created under 100 pixels in size. Accepts a number. The default is 100 (100 pixels).
• resize: optional. The multiplier from which to reduce the width of the image for the next resize iteration. For example, if the image provided is 1000 pixels in size and this parameter is set to 0.7, then the next image created will be (1000 * 0.7) = 700 pixels in size. Accepts a number. The default is 0.75.

pattern

Only files that match this pattern will be processed. So this Metalsmith JavaScript configuration or metalsmith.json:

JavaScript

const Metalsmith = require('metalsmith');
const srcset = require('metalsmith-srcset');

Metalsmith(__dirname)
  .use(srcset({
    pattern: 'blog/**/*.html',
  }))
  .build((err, files) => {
    if (err) { throw err; }
  });

JSON

{
  "source": "src",
  "destination": "build",
  "plugins": {
    "metalsmith-srcset": {
      "pattern": "blog/**/*.html"
    }
  }
}

Would only create multiple image files from the HTML files within the ./src/blog folder, because the pattern is relative to your source folder. See multimatch for further details.

minWidth

No image files will be resized below this width (in pixels). So this Metalsmith JavaScript configuration or metalsmith.json:

JavaScript

const Metalsmith = require('metalsmith');
const srcset = require('metalsmith-srcset');

Metalsmith(__dirname)
  .use(srcset({
    minWidth: 100,
  }))
  .build((err, files) => {
    if (err) { throw err; }
  });

JSON

{
  "source": "src",
  "destination": "build",
  "plugins": {
    "metalsmith-srcset": {
      "minWidth": 100
    }
  }
}

Will prevent image files from being created below this width.

resize

Only files that match this pattern will be processed. So this Metalsmith JavaScript configuration or metalsmith.json:

JavaScript

const Metalsmith = require('metalsmith');
const srcset = require('metalsmith-srcset');

Metalsmith(__dirname)
  .use(srcset({
    resize: 0.75,
  }))
  .build((err, files) => {
    if (err) { throw err; }
  });

JSON

{
  "source": "src",
  "destination": "build",
  "plugins": {
    "metalsmith-srcset": {
      "resize": 0.67
    }
  }
}

Will resize images by the multiplier 0.67 every iteration of a new image.

License

AGPLv3