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.

npm install gray-matter
4 downloads in the last day
259 downloads in the last week
1 574 downloads in the last month

gray-matter NPM version

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.

TOC

Install

Install with npm

npm i gray-matter --save

Install with bower

bower install 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(str);

results in something like:

{
  "context": {"foo": "bar"},
  "content": "baz",
  "original": "---\nfoo: bar\n---\nbaz"
}

matter.read

Read a file from the file system before parsing.

matter.read('file.md');

Returns:

{
  "context": {"foo": "bar"},
  "content": "baz",
  "original": "---\nfoo: bar\n---\nbaz"
}

matter.exists

Returns true or false if front matter exists:

matter.exists(str);

matter.extend

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.

matter.extend(str, obj);

matter.recontruct

A convenience wrapper around the matter and matter.extend. Extends YAML front matter, then re-assembles front matter with the content of the file.

matter.recontruct(str, obj);

matter.stringify

A convenience wrapper around the matter(str).context method.

matter.stringify(str);

matter.stringifyYAML

Stringify parsed front matter back to YAML.

matter.stringifyYAML(str);

Options

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

lang

Type: String

Default: yaml

The parser to use on the extracted front matter. Valid options include:

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, 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

matter

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"}

matter.extend

Given this page:

---
title: Gray Matter
---
Hooray!

and this config:

var file = require('fs').readFileSync('file.md', 'utf8');
var obj = {
  description: 'A simple to use front matter lib';
};
matter.extend(file, obj);

the result would be:

---
title: Gray Matter
description: A simple to use front matter lib
---
Hooray!

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
  • Don't fail if YAML front matter exists, but no content
  • Don't fail if content exists, but no YAML front matter
  • Have no problem reading YAML files directly
  • Have no problem with complex content, including fenced code blocks containing examples of YAML front matter.
  • Should return an object that contains the parsed YAML front matter and content, as well as the "original" content.

Authors

Jon Schlinkert

Brian Woodward

License

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


This file was generated by verb-cli on March 25, 2014.

npm loves you