Skip to content

Only build a certain subset of an entire metalsmith site.

Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



6 Commits

Repository files navigation


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


Only build a certain subset of an entire metalsmith site.






No packages published