Inky

Inky is an HTML-based templating language that converts simple HTML into complex, responsive email-ready HTML. Designed for Foundation for Emails, a responsive email framework from ZURB.

Give Inky simple HTML like this:

<row>
  <columns large="6"></columns>
  <columns large="6"></columns>
</row>

And get complicated, but battle-tested, email-ready HTML like this:

<table class="row">
  <tbody>
    <tr>
      <th class="small-12 large-6 columns first">
        <table>
          <tr>
            <th class="expander"></th>
          </tr>
        </table>
      </th>
      <th class="small-12 large-6 columns first">
        <table>
          <tr>
            <th class="expander"></th>
          </tr>
        </table>
      </th>
    </tr>
  </tbody>
</table>

Installation

npm install inky --save-dev

Usage

Inky can be used standalone, as a Gulp plugin, or with a CLI. You can also access the Inky parser class directly.

Standalone

var inky = require('inky');

inky({
  src: 'src/pages/**/*.html',
  dest: 'dist'
}, function() {
  console.log('Done parsing.');
});

With Gulp

var inky = require('inky')

function parse() {
  gulp.src('src/pages/**/*.html')
    .pipe(inky())
    .pipe(gulp.dest('dist'));
}

Command Line

Install inky-cli to get the inky command. The first option is a glob of input files, and the second option is a folder to output them to. Add the --watch flag to re-compile when files are added or changed.

npm install inky-cli --global
inky src/pages/**/*.html dist --watch

Doesn't support advanced settings at the moment.

Plugin Settings

• src (String): Glob of files to process. You don't need to supply this when using Inky with Gulp.
• dest (String): Folder to output processed files to. You don't need to supply this when using Inky with Gulp.
• components (Object): Tag names for custom components. See custom components below to learn more.
• columnCount (Number): Column count for the grid. Make sure your Foundation for Emails project has the same column count in the Sass as well.
• cheerio (Object): cheerio settings (for available options please refer to cheerio project at github).

Custom Elements

Inky simplifies the process of creating HTML emails by expanding out simple tags like <row> and <column> into full table syntax. The names of the tags can be changed with the components setting.

Here are the names of the defaults:

{
  button: 'button',
  row: 'row',
  columns: 'columns',
  container: 'container',
  inky: 'inky',
  blockGrid: 'block-grid',
  menu: 'menu',
  menuItem: 'item'
}

Extending and Creating Elements

You can extend current elements or create new ones.

var Inky = require('inky').Inky;
var format = require('util').format;

Inky.prototype.componentLibrary.box = function (element) {
  var classes = ['container'];
  if (element.attr('class')) {
    classes = classes.concat(element.attr('class').split(' '));
  }

  return format('<table class="box-wrapper"><tbody><tr><td><table class="%s"><tbody><tr><td>%s</td></tr></tbody></table></td></tr></tbody></table>', classes.join(' '), element.html());
};

var inky = new Inky({
  components: {
    box: 'box'
  }
});

To aid the organisation of new custom elements, a helper named Inky.createCustomComponents accepts an object of components.

// components.inky.js

var format = require('util').format;

module.exports = {
  box: {
    js: function (element) {
      var classes = ['container'];
      if (element.attr('class')) {
        classes = classes.concat(element.attr('class').split(' '));
      }

      return format('<table class="box-wrapper"><tbody><tr><td><table class="%s"><tbody><tr><td>%s</td></tr></tbody></table></td></tr></tbody></table>', classes.join(' '), element.html());
    }
  }
};


// index.js

var Inky = require('inky').Inky;
var format = require('util').format;
var components = require('./components.inky.js');

var inky = new Inky({
  components: Inky.createCustomComponents(components)
});

Programmatic Use

The Inky parser can be accessed directly for programmatic use. It takes in a Cheerio object of HTML, and gives you back a converted Cheerio object.

var Inky = require('inky').Inky;
var cheerio = require('cheerio');

var options = {};
var input = '<row></row>';

// The same plugin settings are passed in the constructor
var i = new Inky(options);
var html = cheerio.load(input)

// Now unleash the fury
var convertedHtml = i.releaseTheKraken(html);

// The return value is a Cheerio object. Get the string value with .html()
convertedHtml.html();