Metalsmith plugin that copies and renames files
JavaScript
Permalink
Failed to load latest commit information.
lib Merge branch 'skip-unchanged' of https://github.com/timdp/metalsmith-… Oct 6, 2016
test allow force overwrite Oct 4, 2016
.gitignore
LICENSE
README.md
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 indication files should be moved instead of copied.
  • force is a boolean value that defaults to false, but you can pass in true to force overwriting of destination files

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

}