gray-matter

A simple-to-use Front-Matter parsing and extraction Library.

• Use custom delimiters
• Will extract and parse YAML, JSON, or CoffeeScript.
• Easy to add additional parsers!

npm i gray-matter --save

Usage

var matter = require('gray-matter');
matter(String, Object);

Methods

matter

By default the matter() method expects a string. So this:

matter('---\nTitle: This is matter\n---\n<p>This is content.<p>');

results in:

{
  "context": {
    "title": "This is matter"
  },
  "content": "<p>This is content.<p>",
  "original": "---\nTitle: This is matter\n---\n<p>This is content.<p>"
}

matter.read

To read a file from the file system before parsing, use matter.read:

matter.read('file.md');

matter.exists

To check for YAML front matter, returning true or false if it exists, use matter.exists:

matter.exists('file.md');

Options

All methods will accept an options object to be passed as a second paramer

lang

Type: String

Default: yaml

The parser to use on the extracted front matter. Valid options are, yaml, coffee and json.

delims

Type: Object

Default: {delims: ['---', '---']}

Open and close delimiters can be passed in as an array of strings. Example:

matter.read('file.md', {delims: ['~~~', '~~~']});

You may also pass an array of arrays, allowing multiple alternate delimiters to be used. Example:

{
  delims: [
    ['---', '~~~'], ['---', '~~~']
  ]
}

Note that passing multiple delimiters will yield unpredictable results, so it is recommended that you use this option only for testing purposes.

autodetect

Type: Boolean

Default: undefined

Attempts to automatically register a language that is specified after the first code boundary (delimiter).

Usage Example:

--- coffee
user = 'jonschlinkert'
reverse = (src) ->
  src.split('').reverse().join('')
---
{%= user %}
{%= reverse(user) %}

Examples

Let's say our page, foo.html contains

---
title: YAML Front matter
description: This is a page
---
<h1>{{title}}</h1>

then running the following in the command line:

console.log(matter('foo.html'));

returns

{
  "context": {
    "title": "YAML Front matter",
    "description": "This is a page"
  },
  "content": "<h1>{{title}}</h1>",
  "original": "---\ntitle: YAML Front matter\n---\n<h1>{{title}}</h1>"
}

and

console.log(matter('foo.html').context);

returns

{"title": "YAML Front matter", "description": "This is a page"}

Authors

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Brian Woodward

• github/doowb
• twitter/doowb

License

Copyright (c) 2014 Jon Schlinkert, Brian Woodward, contributors. Released under the MIT license

This file was generated by grunt-readme on Monday, January 27, 2014.