Uses generated responsive image resolutions :: Those generated by metalsmith-picset-generate display in browser via a <picture> element
Switch branches/tags
Nothing to show
Clone or download
Latest commit 3237252 Feb 21, 2017

Uses picture sets generated by metalsmith-picset-generate to give browsers choice

Example use

Add to your pipeline like

npm i metalsmith-picset-handlebars-helper --save
const picsetHandlearsHelper = require('metalsmith-picset-handlebars-helper')


  • You have a handlebars package installed somewhere either directly or as a sub-dependency (We use that same version / install)
  • /img/picset/anthony_80webp_90jpg_2000,1000,500w.jpg as a 2000px wide 90% quality photo
  • metalsmith-picset-generate is used earlier in your metalsmith pipeline

Then use the handlebars helper like {{{picset "anthony" 500}}} to output something like

	<source type="image/webp"
		srcset="img/srcsets/anthony-2000.webp 2000w, img/srcsets/anthony-1000.webp 1000w, img/srcsets/anthony-500.webp 500w" sizes="100vw" />
	<img src="img/srcsets/anthony-500.jpg"
		srcset="img/srcsets/anthony-2000.jpg 2000w, img/srcsets/anthony-1000.jpg 1000w, img/srcsets/anthony-500.jpg 500w" sizes="100vw" />


Metalsmith requirements

  • You have a handlebars package installed somewhere either directly or as a sub-dependency (We use that same version / install)

Metalsmith options object

	path: 'img/picset'


  • Relative to Metalsmith source folder
  • Default: img/picset/

Helper use


  • Parameter 1 (NAME): Image source name
  • Parameter 2 (DEFAULT_WIDTH): Default width
  • Parameter 3 (SIZES): Optional sizes
  • Parameter 4 (ALT): Optional alt tag

Generates <picture> elements with:

  • srcset parameters that include all files found following metalsmith-picset-generate's naming convention
  • <source> with .webp type in srcset
  • <img> with:
  • srcset with file type of .jpg, .png, or .svg as a fallback
  • src at default width and same file type as it's srcset
  • sizes attribute as specified duplicated on both the <source> and <img ...> tags

Background info


  • Convention over Configuration
  • Simple case of resizing only (artistic decisions not thought through for this)
  • Give the browser all availble choices
  • Reduce bandwidth bloat and keep high quality:
  1. .webp is first choice
  2. Responsive size is first choice
  3. Always give fallbacks
  • Standards based (Using <picture> with inner <img src="..."> fallback)



  • Implemented on Node v6.9.1, untested in other versions
  • Doesn't install handlebars, as assumes you have it in your MetalSmith install and we want to use that same version