gray-matter
Front-matter parsing done right. Fast, reliable and easy to use. Parses YAML front matter by default, but also has support for YAML, JSON, TOML or Coffee Front-Matter, with options to set custom delimiters.
Highlights
- Reliable and battle-tested with assemble, verb, and many other projects!
- Will extract and parse:
- Easy to add additional parsers! pull requests welcome!
Example TOC
Install with npm
npm i gray-matter --save
Install with bower
bower install gray-matter --save
Usage
var matter = require('gray-matter');
matter('---\ntitle: Front Matter\n---\nThis is content.');
API
Parses a string
of front-matter with the given options
, and returns an object.
string
{String}: The string to parse.options
{Object}
delim
{Array}: Custom delimiters formatted as an array. The default is ['---', '---']
.parser
{Function}: Parser function to use. js-yaml is the default.
returns
{Object}: Valid JSON
matter('---\ntitle: foo\n---\nbar');
Read a file and parse front matter. Returns the same object as matter()
.
fp
{String}: file path of the file to read.options
{Object}: Options to pass to gray-matter.returns
: {Object}
matter.read('home.md');
Stringify an object to front-matter-formatted YAML, and concatenate it to the given string.
str
{String}: The content string to append to stringified front-matter.data
{Object}: Front matter to stringify.options
{Object}: Options to pass to js-yamlreturns
: {String}
matter.stringify('foo bar baz', {title: 'Home'});
Results in:
---
title: Home
---
foo bar baz
Options
All methods accept an options object passed as the last argument
options.eval
Type: Boolean
Default: false
Evaluate coffee-script, CSON or JavaScript in front-matter. If you aren't aware of the dangers, google is your friend.
options.lang
Type: String
Default: yaml
The parser to use on the extracted front matter.
YAML is parsed by default, and the languages listed below are parsed automatically if the language is specified after the first delimiter (e.g. ---
).
Valid languages are:
yaml
json
coffee
cson
toml
js
|javascript
Example
To parse coffee front matter, you would define it as follows:
---coffee
title: 'coffee functions'
user: 'jonschlinkert'
fn:
reverse = (src) ->
src.split('').reverse().join('')
---
<%= description %>
<%= reverse(user) %>
options.delims
Type: Object
Default: {delims: ['---', '---']}
Open and close delimiters can be passed in as an array of strings.
Example:
matter.read('file.md', {delims: ['~~~', '~~~']});
would parse:
~~~
title: Home
~~~
This is the {{title}} page.
Example
Given we have a page, abc.html
, containing:
---
title: YAML Front matter
description: This is a page
---
<h1>{{title}}</h1>
then running the following in the command line:
matter('abc.html');
returns
{
"data": {
"title": "YAML Front matter",
"description": "This is a page"
},
"content": "<h1>{{title}}</h1>",
"original": "---\ntitle: YAML Front matter\n---\n<h1>{{title}}</h1>"
}
Why?
Why another YAML Front Matter library?
Because other libraries we tried failed to meet our requirements with Assemble. Some most of the libraries met most of the requirements, but none had all of them. Here are the most important:
- Be usable, if not simple
- Allow custom delimiters
- Use a dependable and well-supported library for parsing YAML and other languages
- Don't fail when no content exists
- Don't fail when no front matter exists
- Have no problem reading YAML files directly
- Have no problem with complex content, including fenced code blocks that contain examples of YAML front matter. Other parsers fail on this.
- Should return an object that contains the parsed YAML front matter and content, as well as the "original" content.
Run tests
npm test
Authors
Jon Schlinkert
License
Copyright (c) 2015 Jon Schlinkert
Released under the MIT license
This file was generated by verb on January 15, 2015.