After mucking about for a bit I landed on the following configuration for Metalsmith.

Metalsmith(__dirname)
    .metadata({})
    .source('./src')
    .destination('./build')
    .clean(true)
    .use(less())
    .use(slug())
    .use(collections({
        works: {
            pattern: 'works/*.md',
            sortBy: 'date',
            reverse: true,
            refer: false
        }
    }))
    .use(markdown())
    .use(jquery('**/*.html', function($) {
        let img = $('img');
        img.addClass('b-lazy');
        img.each((i, el) => {
            let src = $(el).attr('src');
            let lowsrc = src.replace('/images', '/images/thumbs');
            $(el).attr('src', lowsrc);
            $(el).attr('data-src', src);
        });
    }))
    .use(permalinks({
        relative: false,
        pattern: 'works/:date/:title'
    }))
    .use(layouts())
    .build(err => {
        if (err) {
            console.log(err);
            throw err;
        }
    });

This starts with a direct lift from their documentation, to which I added Less compilation, a URL slugger, and a little “jQuery” post processing.

The “jQuery” plugin is actually a wrapper around Cheerio - which is a small implementation of the jQuery API for Node. I’m using this plugin to grab all the images in the resulting markdown-converted HTML and set them up for use with a lazy-loader. This way the markdown document can remain simple and clear of HTML.

I still think Metalsmith could use some better documentation and error handling. Debugging plugins exist but they’re not included in the examples. Overall, though, it’s a very good static site builder. I’m using Serve as a development server locally and Watch to rebuild files as I work. All together it’s a nice little web-site building toolkit.