0.4.1 • Public • Published


This is a plugin for Metalsmith that copies files matching a pattern based on either a transform function or a directory and extension. Think of metalsmith-copy as a file converter plugin like metalsmith-markdown, but it doesn't make any changes to the content and name changes are programmatically specified in its options.


If using the CLI for Metalsmith, metalsmith-copy can be used like any other plugin by including it in metalsmith.json. For example:

  "plugins": {
    "metalsmith-copy": {
      "pattern": "*.md",
      "directory": "markdown-files"

Note that the transform option cannot be used, as JSON doesn't serialize JavaScript functions.

For Metalscript's JavaScript API, metalsmith-copy can be used like any other plugin, by attaching it to the function invocation chain on the Metalscript object. For example:

var copy = require('metalsmith-copy');
    pattern: '*.md',
    transform: function (file) {
      return file + '.bak';


metalsmith-copy requires a pattern option as well as at least one of the transformation options: extension, directory, or transform.

  • pattern is a globbing pattern that specifies which files to copy.

  • extension is an extension (starting with .) that replaces the file's current last extension.

  • directory is a directory relative to the build directory for the new file to be copied.

  • transform supercedes both extension and directory and is a function which takes one argument (the path to the file being copied) and returns a new path for the file to be copied to.

  • move is boolean value indicating files should be moved instead of copied.

  • force is a boolean value that will force overwriting destination files. By default, this is false and overwrites will generate errors.

  • ignore is a globbing pattern that ignores files, overriding a match with pattern.

Use Cases

If you're running a blog, perhaps you want to mimic John Gruber's articles, where he provides both an HTML version of his article and a Markdown version (ending in .text). To set this up with metalsmith-copy, provide the following options to the plugin:

  "pattern": "articles/*.md",
  "extension": ".text"

To move all files in a given folder to the root of your build directory, you could try the following options:

  "pattern": "static/*",
  "directory": "",
  "move": true




Package Sidebar


npm i metalsmith-copy

Weekly Downloads






Unpacked Size

11.6 kB

Total Files


Last publish


  • mattwidmann