# gray-matter [![NPM version](https://badge.fury.io/js/gray-matter.svg)](http://badge.fury.io/js/gray-matter) [![Build Status](https://travis-ci.org/jonschlinkert/gray-matter.svg)](https://travis-ci.org/jonschlinkert/gray-matter) > 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. See the [benchmarks](#benchmarks). gray-matter is 20-30x faster than [front-matter](https://github.com/jxson/front-matter). ## Highlights * Reliable and battle-tested by [metalsmith](https://github.com/segmentio/metalsmith), [assemble](https://github.com/assemble/assemble), [verb](https://github.com/assemble/verb), and many other projects! * Extracts and parses: - [YAML](http://github.com/nodeca/js-yaml) - [JSON](http://en.wikipedia.org/wiki/Json) - [TOML](http://github.com/mojombo/toml) - [CoffeeScript](http://coffeescript.org) when `options.eval` is set to `true` - [CSON](https://github.com/bevry/cson) when `options.eval` is set to `true` - JavaScript: when `options.eval` is set to `true` * Easy to add additional parsers! pull requests welcome! ## Install Install with [npm](https://www.npmjs.com/) ```sh $ npm i gray-matter --save ``` Install with [bower](http://bower.io/) ```sh $ bower install gray-matter --save ``` ## Usage ```js var matter = require('gray-matter'); matter('---\ntitle: Front Matter\n---\nThis is content.'); ``` Returns: ```js { 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. *** ## API ### [matter](index.js#L30) Parses a `string` of front-matter with the given `options`, and returns an object. **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](https://github.com/nodeca/js-yaml)is the default. * `returns` **{Object}**: Valid JSON **Example** ```js matter('---\ntitle: foo\n---\nbar'); //=> {data: {title: 'foo'}, content: 'bar', orig: '---\ntitle: foo\n---\nbar'} ``` ### [.read](index.js#L134) Read a file and parse front matter. Returns the same object as `matter()`. **Params** * `fp` **{String}**: file path of the file to read. * `options` **{Object}**: Options to pass to gray-matter. * `returns` **{Object}** **Example** ```js matter.read('home.md'); ``` ### [.stringify](index.js#L165) Stringify an object to front-matter-formatted YAML, and concatenate it to the given string. Results in: **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-yaml * `returns` **{String}** **Examples** ```js matter.stringify('foo bar baz', {title: 'Home'}); ``` ```yaml --- title: Home --- foo bar baz ``` ## Options > All methods exposed on the API accept an options object passed as the last argument ## options.parser 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](https://github.com/nodeca/js-yaml). **Example** ```js matter(str, { parser: require('js-yaml').safeLoad }); ``` ## options.eval 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. ## options.lang 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: * `yaml` * `json` * `coffee` * `cson` * `toml` * `js`|`javascript` **Example** To parse coffee front matter, you would define it as follows: ```js ---coffee title: 'coffee functions' user: 'jonschlinkert' fn: reverse = (src) -> src.split('').reverse().join('') --- <%= description %> <%= reverse(user) %> ``` ## options.delims Type: `String` Default: `---` Open and close delimiters can be passed in as an array of strings. **Example:** ```js // 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.## Example usage Given we have a page, `abc.html`, containing: ```html --- title: YAML Front matter description: This is a page ---