README.md

metalsmith-convert

This readme isn't correct anymore. Read the index.js file. This fork isn't hosted on npm.

This is a plugin for Metalsmith that uses node-imagemagick-native to convert image-files

Continuous testing courtesy of travis-ci:

Installation

This module is released via npm, install the latest released version with

npm install --save metalsmith-convert

Dependencies

This module uses node-imagemagick-native. You must be able to compile c++ code to install imagemagick-native. The Readme provides instructions for Linux, Mac OS X and Windows respectively.

Usage

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

{
  "plugins": {
    "metalsmith-convert": {
      "src": "**/*.svg",
      "target": "png"
    }
  }
}

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

var convert = require('metalsmith-convert');
require('metalsmith')(__dirname)
  .use(convert({
    src: '**/*.svg',
    target: 'png'
  })
  .build();

Options

metalsmith-convert requires the src options, if target is not given, files will be converted to the source-format.

• src is a globbing pattern that specifies which files to convert
• target is an imagemagick format specifier
• extension the file extension to use for the conversion target (starting with .). Set to "." + target if not given explicitly.
• remove if set to true, don't include the source-file in the build directory.
• resize set to {width: XXX, height: YYY} to resize the image; the name will reflect the size (name_XXX_YYY.ext) if nameFormat is not given.
  • resizeStyle: optional. default: 'aspectfill'. can be 'aspectfit','fill'. Must be added as a parameter to the resize option.
    • aspectfill: keep aspect ratio, get the exact provided size.
    • aspectfit: keep aspect ratio, get maximum image that fits inside provided size
    • fill: forget aspect ratio, get the exact provided size
• rename_only omits the call to ImageMagick and renames the file if set to true.
• nameFormat give the format for the names of the converted files, the following placeholders are available
  • %b the basename of the source file, e.g. given source.png, the value will be source
  • %e the extension of the target format, including the dot
  • %x the width of the resulting image
  • %y the height if the resulting image
• renameSourceFormat: the name-format to rename the source files in the result/build to. Accepts the same place-holders as nameFormat.

The plugin also forwards certain options directly to imagemagick-native, these options are density, blur, rotate, flip, strip, gravity and quality. See imagemagick-native docs for more info.

• It is possible to pass options as array of option-objects to implement multiple rules, e.g. resize to two sizes for different thumbnail sizes:

{
  "plugins": {
    "metalsmith-convert": [
      {
        "src": "**/*.svg",
        "target": "png",
        "resize": {width: 320, height: 240},
        "nameFormat": "%b_thumb%e"
      },
      {
        "src": "**/*.svg",
        "target": "png",
        "resize": {width: 640, height: 480, resizeStyle: 'aspectfit'},
        "nameFormat": "%b_thumb_large%e"
      }
    ]
  }
}

• Resize images without format conversion:

{
  "plugins": {
    "metalsmith-convert":
      {
        "src": "**/*.svg",
        "resize": {width: 320, height: 240},
        "nameFormat": "%b_thumb%e"
      },
  }
}

• Convert to the source name, but keep the original under a different name:

{
  "plugins": {
    "metalsmith-convert":
      {
        "src": "**/*.svg",
        "resize": {width: 320, height: 240},
        "nameFormat": "%b_thumb%e"
        "renameSourceFormat": "%b_orig_%e"
      },
  }
}

Development

To speed up your development cycle you can use the rename_only option, pictures will not be processed and have a potentially wrong file ending, but if your setup can cope with that, on demand scaling might be preferable to longer conversion times.

Contributions

Contributions are always welcome. Just make sure that all tests pass before sending a pull request. And don't forget to add tests for your contributions!