gray-matter
Advanced tools
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 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.
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 many other projects.
Install with npm:
$ npm install --save gray-matter
See the benchmarks. gray-matter is 20-30x faster than front-matter.
options.eval is set to trueoptions.eval is set to trueoptions.eval is set to truevar matter = require('gray-matter');
matter('---\ntitle: Front Matter\n---\nThis is content.');
Returns:
{
orig: '---\ntitle: Front Matter\n---\nThis is content.',
data: { title: 'Front Matter' },
content: '\nThis is content.'
}
That's it! Just pass a string and gray-matter returns an object.
Parses a string of front-matter with the given options, and returns an object.
Example
matter('---\ntitle: foo\n---\nbar');
//=> {data: {title: 'foo'}, content: 'bar', orig: '---\ntitle: foo\n---\nbar'}
Params
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 JSONRead a file and parse front matter. Returns the same object as matter().
Example
matter.read('home.md');
Params
fp {String}: file path of the file to read.options {Object}: Options to pass to gray-matter.returns {Object}Stringify an object to front-matter-formatted YAML, and concatenate it to the given string.
Results in:
Examples
matter.stringify('foo bar baz', {title: 'Home'});
---
title: Home
---
foo bar baz
Params
str {String}: The content string to append to stringified front-matter.data {Object}: Front matter to stringify.options {Object}: Options to pass to js-yamlreturns {String}All methods exposed on the API accept an options object passed as the last argument
Type: Function
Default: undefined
Pass a custom parser on the options. This is useful if you need to, for example, define custom schemas for [js-yaml].
Example
matter(str, {
parser: require('js-yaml').safeLoad
});
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.
However, if you are aware and you only use front-matter on, say, blog posts for a static site... this feature can be pretty useful.
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:
yamljsoncoffeecsontomljs|javascriptExample
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) %>
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 page.
Given we have a page, abc.html, containing:
---
title: YAML Front matter
description: This is a page
---
<h1></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></h1>",
"original": "---\ntitle: YAML Front matter\n---\n<h1></h1>"
}
Benchmarks for building the bootstrap-blog
gray-matter would process all markdown posts in the bootstrap-blog 20 times before the front-matter library finished processing it once.
front-matter.js x 271 ops/sec ±2.68% (80 runs sampled)
gray-matter.js x 4,294 ops/sec ±0.86% (91 runs sampled)
Misc
gray-matter is 12-20x faster than front-matter when content or front matter actually exist.
#1: complex
front-matter x 338 ops/sec ±1.60% (85 runs sampled)
gray-matter x 10,608 ops/sec ±1.97% (86 runs sampled)
#2: empty
front-matter x 5,755,004 ops/sec ±0.88% (94 runs sampled)
gray-matter x 15,157,998 ops/sec ±0.81% (95 runs sampled)
#3: matter
front-matter x 10,256 ops/sec ±2.18% (92 runs sampled)
gray-matter x 202,026 ops/sec ±0.71% (93 runs sampled)
#4: no-content
front-matter x 10,136 ops/sec ±2.00% (91 runs sampled)
gray-matter x 206,548 ops/sec ±1.16% (94 runs sampled)
#5: no-matter
front-matter x 3,540,817 ops/sec ±0.68% (95 runs sampled)
gray-matter x 7,959,809 ops/sec ±0.73% (91 runs sampled)
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:
data: the parsed YAML front matter, as a JSON objectcontent: the contents as a string, without the front matterorig: the "original" contentPull requests and stars are always welcome. For bugs and feature requests, please create an issue.
| Commits | Contributor |
|---|---|
| 121 | jonschlinkert |
| 7 | RobLoach |
| 2 | doowb |
| 2 | moozzyk |
| 1 | Ajedi32 |
| 1 | ianstormtaylor |
(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)
To generate the readme and API documentation with verb:
$ npm install -g verb verb-generate-readme && verb
Install dev dependencies:
$ npm install -d && npm test
Jon Schlinkert
Copyright © 2016, Jon Schlinkert. Released under the MIT license.
This file was generated by verb-generate-readme, v0.2.0, on October 25, 2016.
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
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.