Broccoli Front Matter Filter

A Broccoli plugin that includes or excludes files from the destination tree based on the values of front matter in the individual files.

Installation

npm install --save-dev broccoli-front-matter-filter

Usage

Assume files with the following content:

• src/ios.md

---
mobile: true
---

## Hello from the phone.

• src/windoz.md

---
desktop: true
---

## Hello from the desktop

Including 'desktop' files:

var filterFrontMatter = require('broccoli-front-matter-filter');

var tree = filterFrontMatter('src', {
  include: function(frontMatter) {
    return frontMatter.desktop === true;
  }
});
// tree will include 'src/windoz.md'

Documentation

filterFrontMatter(inputTree, options)

options.include {Function}

A callback that is passed the value of the parsed front matter. If the callback returns a truthy value, then the file will be included in the destination tree. Otherwise, it will not.

options.removeIfNoFrontMatter {Boolean}

What to do when a file does not include front matter. If true, the file will not be included in the destination tree. Default: false

options.stripFrontMatter {Boolean}

If true, front matter will be removed from the file before going to the destination tree. Otherwise, the file will be left alone. Note, caching is not implemented in this library yet which means values of true will modify any files with front matter. The result is slower incremental rebuild time that increases as the number of files with front matter increases. Until caching is implemented, it is recommended to keep this value set to false. Default: false

options.grayMatter {Object}

This uses gray-matter for front matter parsing. Gray matter supports additional features like configuring the type of front matter, evaluating the front matter, if you wish to use coffeescript or javascript, and specifying different delimiters (amongst other features). Any options provided here will be passed through to the gray matter parser. So, to support multiple types of front matter delimiters, you could do:

var tree = filterFrontMatter('src', {
  grayMatter: {
    delims: [ '\\/\\*\\* yaml', '\\*\\*\\/' ]
  },
  include: function(frontMatter) {
    return frontMatter.desktop === true;
  }
});

Note: the delims are converted to regular expressions. If you wish to use characters that are reserved in regular expressions as delimiters, then you must escape them both from the defining string and to the regular expression (hence the double backslashes).