gray-matter
Advanced tools
A simple to use and extend front matter library. Supports parsing and extracting YAML, JSON, TOML or Coffee Front-Matter, with options to set custom delimiters.
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.
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);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.
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.
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.
A simple to use and extend front matter library. Supports parsing and extracting YAML, JSON, TOML or Coffee Front-Matter, with options to set custom delimiters.
Install with npm
npm i gray-matter --save
Install with bower
bower install gray-matter --save
var matter = require('gray-matter');
matter(String, Object);
By default the matter() method expects a string. So this:
matter(str);
results in something like:
{
"context": {"foo": "bar"},
"content": "baz",
"original": "---\nfoo: bar\n---\nbaz"
}
Read a file from the file system before parsing.
matter.read('file.md');
Returns:
{
"context": {"foo": "bar"},
"content": "baz",
"original": "---\nfoo: bar\n---\nbaz"
}
Returns true or false if front matter exists:
matter.exists(str);
Extend and stringify YAML front matter. Takes an object as the second parameter, and returns either the extended, stringified object (YAML), or if no front matter is found an empty string is returned.
matter.extend(str, obj);
A convenience wrapper around the matter and matter.extend. Extends YAML front matter, then re-assembles front matter with the content of the file.
matter.recontruct(str, obj);
A convenience wrapper around the matter(str).context method.
matter.stringify(str);
Stringify parsed front matter back to YAML.
matter.stringifyYAML(str);
All methods will accept an options object to be passed as a second parameter
Type: String
Default: yaml
The parser to use on the extracted front matter. Valid options include:
yamljsoncoffee requires the coffee-script packagetoml requires the toml packageType: 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: [
['---', '~~~'], ['---', '~~~']
]
}
Note that passing multiple delimiters will yield unpredictable results, it is recommended that you use this option only for testing purposes.
Type: Boolean
Default: undefined
Attempts to automatically register a language that is specified after the first code boundary (delimiter).
Usage Example:
--- coffee
user = 'jonschlinkert'
reverse = (src) ->
src.split('').reverse().join('')
---
{%= user %}
{%= reverse(user) %}
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"}
Given this page:
---
title: Gray Matter
---
Hooray!
and this config:
var file = require('fs').readFileSync('file.md', 'utf8');
var obj = {
description: 'A simple to use front matter lib';
};
matter.extend(file, obj);
the result would be:
---
title: Gray Matter
description: A simple to use front matter lib
---
Hooray!
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:
Jon Schlinkert
Brian Woodward
Copyright (c) 2014 Jon Schlinkert, Brian Woodward, contributors. Released under the MIT license
This file was generated by verb-cli on March 17, 2014.
FAQs
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
The npm package gray-matter receives a total of 674,022 weekly downloads. As such, gray-matter popularity was classified as popular.
We found that gray-matter demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.