gray-matter

Install the gray-matter package using npm to parse front-matter from strings or files.

$ npm install --save gray-matter

Depending on your environment, use the following import patterns:

Node.js (CommonJS):

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

TypeScript:

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

Specify the engine used for parsing front-matter using the language option (defaults to yaml).

Dynamic Detection: If you do not provide a language option, gray-matter can automatically detect the language if it is specified immediately after the opening delimiter (e.g., ---toml).

You can extract an excerpt from the content following the front-matter using the excerpt option.

• excerpt: true: Grabs everything from the end of the front-matter delimiter up to the next delimiter (defaults to ---).
• excerpt: Function: A custom function to control extraction. The function receives file and options as parameters. You can manually set file.excerpt within this function.

Use excerpt_separator to define a custom string (e.g., an HTML comment) as the boundary for the excerpt.

By default, gray-matter handles JSON, YAML, and JavaScript. You can extend this by providing custom engines via the engines option.

An engine can be:

1. A function used for parsing only.
2. An object containing a parse method and an optional stringify method.

If a format does not support stringification, you can implement stringify to throw an error.

const toml = require('toml');

// Engine as a function
const file = matter(str, {
  engines: {
    toml: toml.parse.bind(toml),
  }
});

// Engine as an object with parse and stringify
const file = matter(str, {
  engines: {
    toml: {
      parse: toml.parse.bind(toml),
      stringify: function() {
        throw new Error('cannot stringify to TOML');
      }
    }
  }
});

The matter.stringify(file, data, options) method converts a data object into a stringified format (YAML by default) wrapped in delimiters, and appends it to the provided content string. By default, it supports YAML and JSON.

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

Use matter.read(filepath, options) to synchronously read a file from the file system and parse its front-matter. It returns the same object structure as the main matter() function.

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

The main matter function takes a string or an object containing a content property. It extracts and parses the front-matter (YAML by default) and returns a file object containing the parsed data and the remaining content.

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

When calling matter() or matter.read(), the returned object contains several properties used to access the parsed content and metadata.

Enumerable Properties:

• data {Object}: The parsed front-matter object.
• content {String}: The input string with the front-matter removed.
• excerpt {String}: An excerpt, if defined in the options.
• empty {String}: If front-matter is empty (whitespace, nothing, or just comments), this contains the original string.
• isEmpty {Boolean}: true if the front-matter is empty.

Non-enumerable Properties (for debugging):

• orig {Buffer}: The original input string or buffer.
• language {String}: The language of the parsed front-matter (defaults to yaml).
• matter {String}: The raw, un-parsed front-matter string.
• stringify {Function}: A method to stringify the file by converting file.data and prepending it to file.content.

The following options are deprecated and should be replaced with their modern counterparts: