Metalsmith plugin that copies and renames files
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
LICENSE
README.md
package-lock.json
package.json

README.md

metalsmith-copy

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.

Usage

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');
require('metalsmith')(__dirname)
  .use(copy({
    pattern: '*.md',
    transform: function (file) {
      return file + '.bak';
    }
  }))
  .build();

Options

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
}