# gray-matter [![NPM version](https://badge.fury.io/js/gray-matter.png)](http://badge.fury.io/js/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!


```bash
npm i gray-matter --save
```
## Usage

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

## Methods

### matter

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

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

results in:

```json
{
  "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`:

```js
matter.read('file.md');
```

### matter.exists

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

```js
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:

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

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


```js
{
  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
--- coffee
user = 'jonschlinkert'
reverse = (src) ->
  src.split('').reverse().join('')
---
{%= user %}
{%= reverse(user) %}
```

## Examples

Let's say our page, `foo.html` contains

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

then running the following in the command line:

```js
console.log(matter('foo.html'));
```
returns

```json
{
  "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

```js
console.log(matter('foo.html').context);
```
returns


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


## Authors

**Jon Schlinkert**

+ [github/jonschlinkert](https://github.com/jonschlinkert)
+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

**Brian Woodward**

+ [github/doowb](https://github.com/doowb)
+ [twitter/doowb](http://twitter.com/jonschlinkert)


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

***

_This file was generated by [grunt-readme](https://github.com/assemble/grunt-readme) on Monday, January 27, 2014._

[grunt]: http://gruntjs.com/
[Getting Started]: https://github.com/gruntjs/grunt/blob/devel/docs/getting_started.md
[package.json]: https://npmjs.org/doc/json.html