gray-matter
Version:
A simple to use YAML, JSON or Coffee Front-Matter parsing and extraction library, with options to set custom delimiters.
179 lines (122 loc) • 3.55 kB
Markdown
# gray-matter [](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