Only build a certain subset of an entire metalsmith site.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build only a specific set of files from metalsmith.

The default behavior of metalsmith is to always rebuild everything. The main purpose of this plugin is to try and streamline builds as much as possible during development. (particularly for make users)

Before metalsmith starts writing files, this plugin will delete every reference from the files hash that is not specified to be built. This causes Metalsmith to skip these files during the last phase of the build. (this plugin should be last in order to prevent unwanted side-effects)

Most plugins assume that all files in the build will be available in memory, so we cannot safely reject files from the build at the outset. However, by skipping the I/O required to write those files at the end, we can save some build time, while also allowing make to be used properly.

This plugin goes to great lengths to not change the default behavior of Metalsmith unless it is very clear that is the intent of the dev.

  • Metalsmith.clean must be set to false
  • a METALSMITH_ONLY env var must be set (as a space-separated list of files to only include)


var only = require('metalsmith-only-build');

// make sure this plugin is **last**
  "plugins": {
    // make sure this plugin is **last**
    "metalsmith-only-build": true


build/%.html: articles/%.html
  METALSMITH_ONLY="%<" metalsmith