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

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:
  • YAML
  • JSON
  • TOML
  • CoffeeScript when options.eval is set to true
  • CSON when options.eval is set to true
  • JavaScript: when options.eval is set to true
• Easy to add additional parsers! pull requests welcome!

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.');

Run tests

npm test

API

matter

Parses a string of front-matter with the given options, and returns an object.

• string {String}: The string to parse.
• options {Object}
  • delims {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');
//=> {data: {title: 'foo'}, content: 'bar', orig: '---\ntitle: foo\n---\nbar'}

.read

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

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-yaml
• returns: {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.

Authors

Jon Schlinkert

• github/assemble
• twitter/assemble

License

Copyright (c) 2014 Jon Schlinkert
Released under the MIT license

---

This file was generated by verb on December 05, 2014.