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

A simple-to-use Front-Matter parsing and extraction Library.

• Use custom delimiters
• Will extract and parse YAML, JSON, or CoffeeScript.
• Easy to add additional parsers!

npm i 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('---\nTitle: This is matter\n---\n<p>This is content.<p>');

results in:

{
  "context": {
    "title": "This is matter"
  },
  "content": "<p>This is content.<p>",
  "original": "---\nTitle: This is matter\n---\n<p>This is content.<p>"
}

matter.read

To read a file from the file system before parsing, use matter.read:

matter.read('file.md');

matter.exists

To check for YAML front matter, returning true or false if it exists, use matter.exists:

matter.exists('file.md');

Options

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

format

Type: String

Default: yaml

The parser to use on the extracted front matter. Valid options are, yaml, coffee and json.

delimiters

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: [
    ['---', '~~~'], ['---', '~~~']
  ]
}

However, passing multiple delimiters will yield unpredictable results, so it is recommended that you use this option only for testing purposes.

Examples

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

Authors

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Brian Woodward

• github/doowb
• twitter/doowb

License

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

---

This file was generated by grunt-readme on Monday, January 27, 2014.