grunt-gray-matter

grunt-gray-matter

A Grunt task for extracting data header from file contents using Gray Matter

Getting Started

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.

Install plugin with following command:

npm install grunt-gray-matter --save

Once installed, eenable task inside your Gruntfile:

grunt.loadNpmTasks('grunt-gray-matter')

Add minimal configuration for task in Gruntfile:

grunt.initConfig
  grayMatter:
    build:
      src: 'source/templates/{,**/}*.html'
      dest: 'data/matter.json'

Finally, run task with following command:

grunt grayMatter

The grayMatter task

Task scans specified in files src files, reads Gray Matter (Front Matter) header with Gray Matter and outputs collected result in form of JSON to specified dest file.

Path of each discovered src will serve as property in final JSON for extracted Gray Matter data of that src.

Options

options.baseDir

Type: String Default: ''

Path portion which should be subtracted from path to discovered src file.

Result will be used in dest file JSON as property of extracted Gray Matter data.

@config 'grayMatter',
  build:
    options:
      baseDir: 'source/templates'
    src: 'source/templates/page.html'
    dest: 'matter.json'

Will result in

{
  "page": {
    "html": {
      ...
    },
  }
}

instead of

{
  "source/templates/page": {
    "html": {
      ...
    },
  }
}

options.preprocessPath

Type: Function Default: undefined

Allows to alter path (property) under which extracted Matter data will be placed in dest JSON file.

Nesting will be done with _.set, thus any . in path or array of strings will result in nesting data deeper.

You can see here as Kotsu uses this option to mirror templates directory structure in final JSON.

Will be invoked with injected values for following arguments:

• path — formed after subtracting options.baseDir path of current src, used to nest data in final JSON;
• filepath — filepath of current src.

this will correspond to current file of task.

Should return altered path in form of String or String[].

options.preprocessMatterData

Type: Function Default: undefined

Allows to alter extracted Gray Matter data for each discovered src.

As for an example, check out how Kotsu injects additional data for each page into final Matter data.

Will be invoked with injected values for following arguments:

• matterData — extracted Matter data of current src;
• path — formed after subtracting options.baseDir path of current src, used to nest data in final JSON;
• filepath — filepath of current src.

this will correspond to current file object.

Should return altered Gray Matter data in form of Object.

options.preprocessData

Type: Function Default: undefined

Allows to alter final data, constructed from extracted Matter data.

Result of this function will be used for printing Object to dest file.

Will be invoked with injected values for following arguments:

• data — extracted and assembled data from all current srces Matter data, processed by preprocessPath and preprocessMatterData (if specified).

this will correspond to current this of task.

Should return altered final data in form of Object, which will be printed to dest file.

options.replacer

Type: Function|String[]|Number[] Default: null

Pass replacer parameter to JSON.stringify().

options.space

Type: String|Integer Default: 2

Pass space parameter to JSON.stringify().

Controls indentation for outputted JSON file.

options.parser

Type: Function Default: undefined

Pass custom parser to Gray Matter.

options.eval

Type: Boolean Default: false

Pass eval parameter to Gray Matter.

Forces Gray Matter to evaluate CoffeeScript or JavaScript in Front Matter.

options.lang

Type: String Default: undefined

Pass lang parameter to Gray Matter.

options.delims

Type: String Default: undefined

Pass delims parameter to Gray Matter.

Usage examples

@config 'grayMatter',
  build:
    options:
      baseDir: 'source/templates'

      preprocessPath: (path) ->
        # do something with paths in constructed json file
        return path

      preprocessMatterData: (data, path, src) ->
        # do something with extracted data
        return data

    src: 'source/templates/{,**/}*.html'
    dest: 'data/matter.json'

Node support

Requires Node 6.0 or higher.

Just in case, grunt-gray-matter 1.2.0 was the last version to support Node 0.10.0. But better go update your Node. Seriously.

Testing

Run npm test to launch tests or npm run test:watch to watch tests. Observe how magic happens.

Testing requires Node >= 4.0.0.

Examples

• Kotsu Web Starter Kit

License

Copyright 2016 Serj Lavrin.

Licensed under the Apache 2.0 license.

Changelog

1.3.0

Added

• Added error catching for Gray Matter with information about file which caused error for easier debugging.

  Now whenever there is an error in Fron Matter, task will not silently ignore it nor will shut down completely. Instead, it will run all files and report all encountered errors.

  If there are any errors by the end of the task, it will throw and exception.

• Added better reporting about successfully processed and failed files.

• Added NPM 5 lockfile.

• Added package.json main property pointing to the task file.

• Added package.json files property to ensure that task directory will be always preserved.

• Added snazzy for better standard output.

Changed

• Raised minimum required Node version to 6.0.

• Updated dependencies.

• Updated Gray Matter to version 3.0.8, which resolved gray-matter#37.

  No longer task will silently fail when Front Matter contains syntax errors :guitar:

• Replaced lodash with lodash.set to minimize dependencies.

• Grunt and task files rewritten in pure JavaScript. Sorry, CoffeeScript :broken_heart:

• Added .editorconfig.

  Somehow it was missing for all that time, but still I slept without nightmares.

• Other internal cleanups and improvements.