Metalsmith 2.7 released

← News overview

Metalsmith 2.7 is out! It's long overdue, but the Ukraine war, ensuing energy crisis, rising cost of living, home renovations and the explosion of AI have all taken their toll on my ability to spend time on Metalsmith, but it's here at last. And it is quite a substantial semver-minor release.

Github release | Github Roadmap 2.7 issue | NPM package | Node >= 16.0.0

Highlights

Metalsmith#statik

metalsmith.statik was added after many deliberations weighing its benefits, and is the built-in option to designate static files with the guarantee that the files' contents will not be altered by plugins during the build.

The method is named with a statik instead of static to avoid naming collision with the reserved class keyword static.

Metalsmith.statik has a function signature similar to metalsmith.ignore, takes one or more more globs/paths:

metalsmith.statik(['assets/**','CNAME'])

Inside plugins the metalsmith.statik() getter returns a files object just like the non-static files object, with the key difference that its' files' contents, stats and mode are read-only. The file.contents are never actually read, but contain the original path of the file relative to metalsmith.source(). Only files inside

Static files are copied to metalsmith.destination() before processed files. If a file path is in both processed and static files, the static file will be overwritten. This is an edge case that could arise when files are added dynamically.

Plugins or users can still designate extra files as static, remove or overwrite them during the build. This is useful for example to avoid plugins from further modifying the file after a certain point.

function makeHtaccessStatic(files, metalsmith) {
  const statik = metalsmith.statik()

  const htaccess = '.htaccess'

  // designate a regular file static
  statik[htaccess] = { ...files[htaccess], contents: Buffer.from('.htaccess') }
  // if you don't remove the original, it will overwrite the static one
  delete statik[htaccess]

  // 'clone' a static file to another destination
  statik[htaccess] = statik['dotfiles/.htaccess']
  // 'clone' + remove original = move
  delete statik['dotfiles/.htaccess']

  // convert a static file to a non-static one (unusual use case)
  files[htaccess] = {
    ... statik[htaccess],
    contents: fs.readFileSync(metalsmith.path(metalsmith.source(), htaccess))
  }
}

With this addition, the plugins metalsmith-assets and metalsmith-static are completely obsolete and have been removed from the plugin registry

Metalsmith#imports

metalsmith.imports() is a utility for the metalsmith CLI and plugins (like @metalsmith/layouts' transform option) to load (C/M)JS & JSON modules specified as string.
It also has support for loading a named export via the second parameter:

await metalsmith.imports('metalsmith') // Metalsmith
await metalsmith.imports('data.json')  // object
await metalsmith.imports('./helpers/index.js', 'formatDate')  // function

CLI: metalsmith init

Starting from v2.7.0 the metalsmith init command can be used to start a new metalsmith project, provided that git is installed and available in $PATH. The default command will pull the content from starters/bare in the metalsmith/resources repo into the current directory.

In the future, other starters or examples or minimal repro's can be loaded from the default repo, so that you could do for ex metalsmith init starters/express or metalsmith init examples/using-plugins.

# default
metalsmith init
# explicit default
metalsmith init starters/bare . --origin=https://github.com/metalsmith/resources

However, you can use metalsmith init to pull any git repository's subfolder contents without git history - ideal for usage as template/starter/etc (also local!). For example, the command below would pull all "solid"-style SVG source files from the FontAwesome repository into the fa-solid directory:

metalsmith init svgs/solid fa-solid --origin=https://github.com/FortAwesome/Font-Awesome

The --force option can be used to force writing to a non-empty directory.

For reference, these are the --help contents of metalsmith init:

metalsmith init --help
Usage: metalsmith init [options] [source] [destination]

Initialize a new metalsmith project from a git repo (subpath). Runs a sequence of git and filesystem commands.
Assumes a working git executable in $PATH and properly configured git/ssh configs.

Arguments:
  source                 Source directory (default: "starters/bare")
  destination            Destination directory, defaults to current directory (default: ".")

Options:
  -f, --force            Force overwriting a non-empty directory (default: false)
  -o, --origin <origin>  Origin repository (https or ssh url, or a directory path). Defaults to https://github.com/metalsmith/resources if omitted (default:
                         "https://github.com/metalsmith/resources")
  -h, --help             display help for command

CLI: metalsmith clean

Metalsmith 2.7.0 CLI bundles a clean utility command that can be used to recursively clean [api_metalsmith_destination] from the command-line. This is useful (a.o) when altering between watch/build modes with partial rebuilds (clean(false)).

For reference, these are the --help contents of metalsmith clean:


Usage: metalsmith clean [options] [destination]

Clean a directory

Arguments:
  destination          Destination directory, defaults to metalsmith.destination()

Options:
  -c, --config [path]  configuration file location (default: "metalsmith.json")
  -h, --help           display help for command

Full Release notes

Added

Removed

Updated

Fixed

× This website may use local storage for purely functional purposes (for example to remember preferences), and anonymous cookies to gather information about how visitors use the site. By continuing to browse this site, you agree to its use of cookies and local storage.