gray-matter
A simple to use and extend front matter library. Supports parsing and extracting YAML, JSON, TOML or Coffee Front-Matter, with options to set custom delimiters.
Used by assemble, verb, and thousands of other projects!
v0.5.0 has breaking changes!
YAML is now parsed using the
.safeLoad()
method from js-yaml.To parse coffee, CSON or javascript front matter, you must set
options.eval
to true.stringify()
has been renamed totoJSON()
stringifyYAML()
has been renamed totoYAML()
Highlights
Reliable and battle-tested.
Will extract and parse:
CoffeeScript when
options.eval
is set totrue
CSON when
options.eval
is set totrue
JavaScript: when
options.eval
is set totrue
Easy to add additional parsers! pull requests welcome!
TOC
Install
Install with npm
Install with bower
Usage
API
Expects a string and returns and object:
str
{String}: The string to parseoptions
{Object}: Object of optionsreturns
{Object}file
: Object with the following properties.
Returns:
Read a file then pass the string and options
to matter()
for parsing:
filepath
{String}options
{Object}returns
{Object}file
: Same object asmatter()
, with an additionalpath
property
Returns something like:
Return true
if front-matter exists.
str
{String}: The string to parseoptions
{Object}: Options to pass tomatter()
returns
{Boolean}true
: orfalse
Extend and stringify YAML front matter. Takes an object as the second parameter, and returns either the extended, stringified object (YAML), or if no front matter is found an empty string is returned.
str
{String}: The string to parseobj
{Object}: The object to use to extend the front matter.returns
{String}: String with extended YAML front matter.
A convenience wrapper around the matter()
and matter.extend()
methods.
str
{String}: The string to parseobj
{Object}: The object to use to extend the front matter.returns
{String}: Original string with extended front matter.
Extends YAML front matter, then re-assembles front matter with the content of the file.
str
{String}options
{Object}returns
{Object}: Parsed front matter as JSON.
Convenience wrapper around the matter(str).data()
method.
str
{String}options
{Object}returns
{String}: Stringified YAML.
Stringify parsed front matter back to YAML.
Options
All methods will accept an options object to be passed as a second parameter
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. Valid options include:
yaml
json
coffee
cson
toml
js
|javascript
options.delims
Type: Object
Default: {delims: ['---', '---']}
Open and close delimiters can be passed in as an array of strings. Example:
You may also pass an array of arrays, allowing multiple alternate delimiters to be used. Example:
Note that passing multiple delimiters will yield unpredictable results, it is recommended that you use this option only for testing purposes.
options.autodetect
Type: Boolean
Default: undefined
Attempts to automatically register a language that is specified after the first code boundary (delimiter).
Usage Example:
Examples
Let's say our page, foo.html
contains
then running the following in the command line:
returns
and
returns
.extend
Given this page:
and this config:
the result would be:
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.
Authors
Jon Schlinkert
License
Copyright (c) 2014 Jon Schlinkert, contributors. Released under the MIT license
This file was generated by verb-cli on October 24, 2014.
Last updated