1.3.3 • Public • Published


Build Status NPM version

A customizable extractor for front matter in various formats (YAML, TOML, etc.) between a pair of delimiters and at the start of a string.


  • Delimiters are customizable. (a language name can be placed next to the first delimiter)
  • Parsers are customizable. (with builtin YAML and TOML parsers)
  • LF (0x0A) and CRLF (\x0D\x0A) are both recognizable newlines.


npm install meta-matter


var matter = require('meta-matter');
matter('---\nfoo: bar\n---\nbaz');
/* return {
  src: "---\nfoo: bar\n---\nbaz",
  body: "baz",
  data: {foo: "bar"}
matter.readFileSync('', {delims: ['--[', ']--']});
--[ TOML
foo = "bar"


matter(string[, options])

Parse a string with or without front matter and return an object.


  • options.loose {Boolean?}: Whether to tolerate ambiguous delimiters. Default: false
  • options.lang {String?}: The name of the parser to use if options.parsers is not a function. Default: 'yaml'
  • options.delims {(String|Array)?}: Custom delimiters. Default: '---' or ['---', '---']
  • options.parsers {(Function|Object)?}: Custom parser(s). Default: {'yaml': matter.parsers.yaml,'toml': matter.parsers.toml}
    • {function(text, {loose: Boolean}): Mixed} A parser function. options.lang will be ignored.
    • {Object.<String, Function>}: A map from languages to parser functions. If no parser is found in it, then search the builtin parsers.

A language name (case-insensitive, lower-case preferred) can be appended to the first delimiter in the source text, e.g. --- YAML, and it will override options.lang but not options.parsers. All builtin languages are "yaml" and "toml".

The returned object has three properties:

  • src {String}: The original input string.
  • body {String}: The input string without front matter. (body.length <= src.length)
  • data {Mixed}: The data returned from the parsers. Default: null (if front matter is missing or whitespace only)

matter.test(string[, options])

Check if a string contains front matter. Only options.loose and options.delims are useful options.

matter.readFile(path[, options], callback)

Read and parse a file asynchronously. The callback function is of type function(error, object).

The returned object will have one more property "path" for the real file path.

matter.readFileSync(path[, options])

Read and parse the file synchronously. It may throw an error when the file is not readable.

The returned object will have one more property "path" for the real file path.

Other properties of matter.


An object with the cache of required modules (lazily loaded):

  • {Object} matter.modules.yaml: require('js-yaml')
  • {Object} matter.modules.toml: require('toml-j0.4')


All builtin parsers (allowed to be modified):

  • {function(str, opts): Mixed} matter.parsers.yaml: The YAML parser.
  • {function(str, opts): Mixed} matter.parsers.toml: The TOML parser.

Currently, opts only has one property loose, which comes from the provided options.

All builtin parsers will return null when an error occurs.


Copyright (c) 2015 Jak Wings. This project was released under the MIT license.

Package Sidebar


npm i meta-matter

Weekly Downloads






Last publish


  • jakwings