@11ty/gray-matter

Reduced and maintained fork of gray-matter originally by Jon Schlinkert.

Current differences:

• Upstream package last released in 2019.
• Upgrades js-yaml major version to v4
• Uses Uint8Array internally instead of Node-env specific Buffer for more runtime compatibility.
• Removes javascript front matter type (removing use of eval)

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, or TOML Front-Matter, with options to set custom delimiters.

Install

Install with npm:

$ npm install --save @11ty/gray-matter

Heads up!

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

What does this do?

const fs = require('fs');
const matter = require('@11ty/gray-matter');
const 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.
• battle-tested: used by assemble, metalsmith, phenomic, verb, generate, update and many others.

Usage

Using CommonJS:

const matter = require('@11ty/gray-matter');

Or ESM:

import matter = require('@11ty/gray-matter');
// OR
import * as matter from '@11ty/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
• file.empty {String}: when the front-matter is "empty" (either all whitespace, nothing at all, or just comments and no data), the original string is set on this property. See #65 for details regarding use case.
• file.isEmpty {Boolean}: true if front-matter is empty.

Non-enumerable

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

• file.orig {Uint8Array}: the original input string (or Uint8Array)
• 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 prepending 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>

Links to examples

• excerpt-separator
• excerpt-stringify
• excerpt
• javascript
• json-stringify
• json
• restore-empty
• sections-excerpt
• sections
• 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

const matter = require('@11ty/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

const 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: Boolean|Function

Default: undefined

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

If set to excerpt: true, it will look for the frontmatter delimiter, --- by default and grab everything leading up to it.

Example

const str = '---\nfoo: bar\n---\nThis is an excerpt.\n---\nThis is content';
const file = matter(str, { excerpt: true });

Results in:

{
  content: 'This is an excerpt.\n---\nThis is content',
  data: { foo: 'bar' },
  excerpt: 'This is an excerpt.\n'
}

You can also set excerpt to a function. This function uses the 'file' and 'options' that were initially passed to gray-matter as parameters, so you can control how the excerpt is extracted from the content.

Example

// returns the first 4 lines of the contents
function firstFourLines(file, options) {
  file.excerpt = file.content.split('\n').slice(0, 4).join(' ');
}

const file =  matter([
  '---',
  'foo: bar',
  '---',
  'Only this',
  'will be',
  'in the',
  'excerpt',
  'but not this...'
].join('\n'), {excerpt: firstFourLines});

Results in:

{
  content: 'Only this\nwill be\nin the\nexcerpt\nbut not this...',
  data: { foo: 'bar' },
  excerpt: 'Only this will be in the excerpt'
}

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

const toml = require('toml');

/**
 * defined as a function
 */

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

/**
 * Or as an object
 */

const 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.

About

$ npm install && npm test

Contributors

Author

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

License

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