File object manipulation / transformation library in the metalsmith pipeline
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

metalsmith-transform

Transform or manipulate file objects in the metalsmith pipeline

npm Build Status Coverage Status

About

metalsmith-transform is a metalsmith plugin which allows the use of custom functions to manipulate the file object in a metalsmith pipeline.

Furthermore, instead of writing a full plugin, you can just pass in the transformation function into this instead.

String methods are inspired by gulp-insert.

Installation

$ npm install metalsmith-transform

or

$ yarn add metalsmith-transform

Usage

API

import transform from 'metalsmith-transform';

You can pass in an object or a function as an argument. i.e.

metalsmith.use(transform(function(fileObject, metalsmithData) {
  return fileObject;
}));

// or

metalsmith.use(transform({
  action: '', // append / prepend / wrap / transform
  value: '', // string | function (only if using transform)
  pattern: '*.md'
}));

CLI

"plugins": {
  "metalsmith-transform": {
    "action": "append",
    "value": "Include Me!"
  }
}

Note on CLI Usage: Since JSON does not take functions, only append, prepend and wrap actions are accepted.

Available Actions

By default, if an action is not defined, append is used.

In the examples below, assume that the content in your files are "I am".

Transform

Calls a function with the file object and metalsmith instance. Function should return the modified contents of the file.

metalsmith.use(transform(function(data, m){
  let contents = data.contents.toString().toUpperCase();
  data.contents = new Buffer(contents);

  return data;
}));

// result: I AM

Append

Appends a string onto the contents.

// Appends 'world' to the content of every file
metalsmith.use(transform({
  action: 'append',
  value: 'world'
}));

// result: I am world

Prepend

Prepends a string onto the contents.

// Prepends 'Hello' to the content of every file
metalsmith.use(transform({
  action: 'prepend',
  value: 'hello'
}));

// result: hello I am

Wrap

Wraps the contents with two strings.

// prepends 'hello' and appends 'world' to the content of every file
metalsmith.use(transform({
  action: 'wrap',
  value: ['hello', 'world']
}));

// result: hello I am world

License

metalsmith-transform is MIT licensed