gray-matter

What is gray-matter?

The gray-matter npm package is used to parse front-matter from strings or files. Front-matter is metadata stored at the top of a file, typically in YAML or JSON format, which is often used in static site generators and other content management systems.

What are gray-matter's main functionalities?

Parsing Front-Matter

This feature allows you to parse front-matter from a string. The front-matter is typically written in YAML or JSON format and is separated from the content by triple dashes (---). The parsed object contains the metadata and the content separately.

const matter = require('gray-matter');
const file = '---\ntitle: Hello World\ndate: 2023-10-01\n---\nThis is the content of the file.';
const parsed = matter(file);
console.log(parsed);

Stringify Front-Matter

This feature allows you to convert a content string and a metadata object back into a string with front-matter. This is useful for generating files with front-matter programmatically.

const matter = require('gray-matter');
const data = { title: 'Hello World', date: '2023-10-01' };
const content = 'This is the content of the file.';
const stringified = matter.stringify(content, data);
console.log(stringified);

Custom Delimiters

This feature allows you to specify custom delimiters for the front-matter. By default, gray-matter uses triple dashes (---), but you can change this to any string you prefer.

const matter = require('gray-matter');
const file = '+++\ntitle = "Hello World"\ndate = "2023-10-01"\n+++\nThis is the content of the file.';
const parsed = matter(file, { delimiters: '+++' });
console.log(parsed);

Other packages similar to gray-matter

front-matter

The front-matter package is another tool for parsing front-matter from strings. It is simpler and has fewer features compared to gray-matter, but it is also lightweight and easy to use.

js-yaml

The js-yaml package is primarily used for parsing and stringifying YAML, but it can also be used to handle front-matter. It is more general-purpose and powerful for YAML processing, but it requires more setup to use for front-matter specifically.

marked

The marked package is a markdown parser that can also handle front-matter if used in conjunction with other tools. It is more focused on converting markdown to HTML, but it can be extended to support front-matter parsing.

README

gray-matter

Parse front-matter from a string or file. 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. Used by metalsmith, assemble, verb and many other projects.

Install

Install with npm:

$ npm install --save gray-matter

Heads up!

Please see the release history to learn about breaking changes that were made in v3.0.

What does this do?

Run this example

Add the HTML in the following example to example.html, then add the following code to example.js and run $ node example (without the $):

var fs = require('fs');
var matter = require('gray-matter');
var str = fs.readFileSync('example.html', 'utf8');
console.log(matter(str));

Converts a string with front-matter, like this:

---
title: Hello
slug: home
---
<h1>Hello world!</h1>

Into an object like this:

{
  content: '<h1>Hello world!</h1>',
  data: { 
    title: 'Hello', 
    slug: 'home' 
  }
}

Why use gray-matter?

• simple: main function takes a string and returns an object
• accurate: better at catching and handling edge cases than front-matter parsers that rely on regex for parsing
• fast: faster than other front-matter parsers that use regex for parsing
• flexible: By default, gray-matter is capable of parsing YAML, JSON and JavaScript front-matter. But other engines may be added.
• extensible: Use custom delimiters, or add support for any language, like TOML, CoffeeScript, or CSON
• battle-tested: used by assemble, metalsmith, phenomic, verb, generate, update and many others.

Rationale

Why did we create gray-matter in the first place?

We created gray-matter after trying out other libraries that failed to meet our standards and requirements.

Some libraries met most of the requirements, but none met all of them.

Here are the most important:

• Be usable, if not simple
• Use a dependable and well-supported library for parsing YAML
• Support other languages besides YAML
• Support stringifying back to YAML or another language
• Don't fail when no content exists
• Don't fail when no front matter exists
• Don't use regex for parsing. This is a relatively simple parsing operation, and regex is the slowest and most error-prone way to do it.
• Have no problem reading YAML files directly
• Have no problem with complex content, including non-front-matter fenced code blocks that contain examples of YAML front matter. Other parsers fail on this.
• Support stringifying back to front-matter. This is useful for linting, updating properties, etc.
• Allow custom delimiters, when it's necessary for avoiding delimiter collision.
• Should return an object with at least these three properties (for debugging):
  • data: the parsed YAML front matter, as a JSON object
  • content: the contents as a string, without the front matter
  • orig: the "original" content

Usage

Using Node's require() system:

var matter = require('gray-matter');

Or with typescript

import matter = require('gray-matter');
// OR
import * as matter from 'gray-matter';

Pass a string and options to gray-matter:

console.log(matter('---\ntitle: Front Matter\n---\nThis is content.'));

Returns:

{
  content: '\nThis is content.',
  data: { 
    title: 'Front Matter' 
  } 
}

More about the returned object in the following section.

---

Returned object

gray-matter returns a file object with the following properties.

Enumerable

• file.data {Object}: the object created by parsing front-matter
• file.content {String}: the input string, with matter stripped
• file.excerpt {String}: an excerpt, if defined on the options

Non-enumerable

In addition, the following non-enumberable properties are added to the object to help with debugging.

• file.orig {Buffer}: the original input string (or buffer)
• file.language {String}: the front-matter language that was parsed. yaml is the default
• file.matter {String}: the raw, un-parsed front-matter string
• file.stringify {Function}: stringify the file by converting file.data to a string in the given language, wrapping it in delimiters and appending it to file.content.

Run the examples

If you'd like to test-drive the examples, first clone gray-matter into my-project (or wherever you want):

$ git clone https://github.com/jonschlinkert/gray-matter my-project

CD into my-project and install dependencies:

$ cd my-project && npm install

Then run any of the examples to see how gray-matter works:

$ node examples/<example_name>

• coffee
• excerpt-separator
• excerpt-stringify
• excerpt
• javascript
• json-stringify
• json
• toml
• yaml-stringify
• yaml

API

matter

Takes a string or object with content property, extracts and parses front-matter from the string, then returns an object with data, content and other useful properties.

Params

• input {Object|String}: String, or object with content string
• options {Object}
• returns {Object}

Example

var matter = require('gray-matter');
console.log(matter('---\ntitle: Home\n---\nOther stuff'));
//=> { data: { title: 'Home'}, content: 'Other stuff' }

.stringify

Stringify an object to YAML or the specified language, and append it to the given string. By default, only YAML and JSON can be stringified. See the engines section to learn how to stringify other languages.

Params

• file {String|Object}: The content string to append to stringified front-matter, or a file object with file.content string.
• data {Object}: Front matter to stringify.
• options {Object}: Options to pass to gray-matter and js-yaml.
• returns {String}: Returns a string created by wrapping stringified yaml with delimiters, and appending that to the given string.

Example

console.log(matter.stringify('foo bar baz', {title: 'Home'}));
// results in:
// ---
// title: Home
// ---
// foo bar baz

.read

Synchronously read a file from the file system and parse front matter. Returns the same object as the main function.

Params

• filepath {String}: file path of the file to read.
• options {Object}: Options to pass to gray-matter.
• returns {Object}: Returns an object with data and content

Example

var file = matter.read('./content/blog-post.md');

.test

Returns true if the given string has front matter.

Params

• string {String}
• options {Object}
• returns {Boolean}: True if front matter exists.

Options

options.excerpt

Type: Object

Default: undefined

Extract an excerpt that directly follows front-matter, or is the first thing in the string if no front-matter exists.

Example

var str = '--\ntitle: Home\n---\nAn excerpt\n---\nOther stuff';
console.log(matter(str, {excerpt: true}));

Results in:

{ 
  data: { title: 'Home'}, 
  excerpt: '\nAn excerpt', 
  content: '\nAn excerpt\n---\nOther stuff' 
}

options.excerpt_separator

Type: String

Default: undefined

Define a custom separator to use for excerpts.

console.log(matter(string, {excerpt_separator: '<!-- end -->'}));

Example

The following HTML string:

---
title: Blog
---
My awesome blog.
<!-- end -->
<h1>Hello world</h1>

Results in:

{ 
  data: { title: 'Blog'}, 
  excerpt: 'My awesome blog.', 
  content: 'My awesome blog.\n<!-- end -->\n<h1>Hello world</h1>' 
}

options.engines

Define custom engines for parsing and/or stringifying front-matter.

Type: Object Object of engines

Default: JSON, YAML and JavaScript are already handled by default.

Engine format

Engines may either be an object with parse and (optionally) stringify methods, or a function that will be used for parsing only.

Examples

var toml = require('toml');

/**
 * defined as a function
 */

var file = matter(str, {
  engines: {
    toml: toml.parse.bind(toml),
  }
});

/**
 * Or as an object
 */

var file = matter(str, {
  engines: {
    toml: {
      parse: toml.parse.bind(toml),

      // example of throwing an error to let users know stringifying is
      // not supported (a TOML stringifier might exist, this is just an example)
      stringify: function() {
        throw new Error('cannot stringify to TOML');
      }
    }
  }
});

console.log(file);

options.language

Type: String

Default: yaml

Define the engine to use for parsing front-matter.

console.log(matter(string, {language: 'toml'}));

Example

The following HTML string:

---
title = "TOML"
description = "Front matter"
categories = "front matter toml"
---
This is content

Results in:

{ content: 'This is content',
  excerpt: '',
  data:
   { title: 'TOML',
     description: 'Front matter',
     categories: 'front matter toml' } }

Dynamic language detection

Instead of defining the language on the options, gray-matter will automatically detect the language defined after the first delimiter and select the correct engine to use for parsing.

---toml
title = "TOML"
description = "Front matter"
categories = "front matter toml"
---
This is content

options.delimiters

Type: String

Default: ---

Open and close delimiters can be passed in as an array of strings.

Example:

// format delims as a string
matter.read('file.md', {delims: '~~~'});
// or an array (open/close)
matter.read('file.md', {delims: ['~~~', '~~~']});

would parse:

~~~
title: Home
~~~
This is the {{title}} page.

Deprecated options

options.lang

Decrecated, please use options.language instead.

options.delims

Decrecated, please use options.delimiters instead.

options.parsers

Decrecated, please use options.engines instead.

Release history

v3.0.0 - June 30, 2007

• adds support for excerpts
• refactored engines (parsers), so that it's easier to add parsers and stringifiers
• options.parsers was renamed to options.engines
• the returned object now has non-enumerable matter and stringify properties

Breaking changes

• toml, coffee and cson are no longer supported by default. Please see options.engines and the examples to learn how to add engines.

About

Related projects

• assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
• metalsmith: An extremely simple, pluggable static site generator. | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Contributors

Commits	Contributor
128	jonschlinkert
7	RobLoach
5	heymind
2	doowb
2	onokumus
2	moozzyk
1	Ajedi32
1	ianstormtaylor

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. Released under the MIT License.

---

This file was generated by verb-generate-readme, v0.6.0, on June 30, 2017.