matter

Flexible front matter parser.

matter.yaml('---\nfoo: bar\n---');
// => {foo: 'bar'}
 
matter.yaml.inFile('./stuff.md', function(err, metadata) {
  // ...
});
 
matter.json('---\n{"foo": "bar"}\n---');
// => {foo: 'bar'}
 
matter.json.inFile('./stuff.md', function(err, metadata) {
  // ...
});

What can it do?

• Parse front matters embedded in comments (or any configurable tokens)
• Allow custom parsers to be plugged in
• Keep the parsing as configurable as possible

API

matter.yaml(string, [options])

Alias to matter.parse.yaml.

console.log(matter.yaml('---\nfoo: bar\n---'));
// => {foo: 'bar'}

matter.yaml.inFile(filepath, [options], callback)

Alias to matter.parse.yaml.inFile.

matter.yaml.inFile('./stuff.md', function(err, metadata, data) {
  if (!err) {
    console.log(metadata);
  };
});

matter.json(string, [options])

Alias to matter.parse.json.

console.log(matter.json('---\n{"foo": "bar"}\n---'));
// => {foo: 'bar'}

matter.json.inFile(filepath, [options], callback)

Alias to matter.parse.json.inFile.

matter.json.inFile('./stuff.md', function(err, metadata, data) {
  if (!err) {
    console.log(metadata);
  };
});

matter.parse.<parserName>(string, [options])

• string: A string containing the front matter to be parsed
• options: An object of options
  • ignore: A regex or string representing tokens to be ignored when extracting the front matter. Used to extract the front matter. The tokens ignored by default are //, /*, */, #.
  • indicator (default=/---/): A regex or string to use as the front matter head and tail indicators
  • indicators: An object of options to use for the front matter head and tail indicators:
    • head: A regex or string to use as the front matter's head indicator. Defaults to indicator's value.
    • tail: A regex or string to use as the front matter's tail indicator. Defaults to indicators's value

Parses a string containing a front matter using the parser registered as parserName.

console.log(matter.parse.yaml('---\nfoo: bar\n---'));
// => {foo: 'bar'}

matter.parse.<parserName>.inFile(filepath, [options], callback)

• filename: A relative or absolute path to the file with the front matter to be parsed
• options: An object of options:
  • encoding (default='utf8'): The encoding to be used when reading the file
  • ignore: A regex or string representing tokens to be ignored when extracting the front matter. Used to extract the front matter. The tokens ignored by default are //, /*, */, #.
  • indicator (default=/---/): A regex or string to use as the front matter head and tail indicators
  • indicators: An object of options to use for the front matter head and tail indicators:
    • head: A regex or string to use as the front matter's head indicator. Defaults to indicator's value.
    • tail: A regex or string to use as the front matter's tail indicator. Defaults to indicators's value
  • [fs.readFile options]
• callback(err, metadata, data): A function to be called when the file has been read and the front matter has been parsed.
  • err: An error object for an error which may have occured while reading and parsing the file. null if no error occured.
  • metadata: An object containing the extracted and parsed front matter data
  • data: A string of the actual data contained in the file

Parses a file containing a front matter using the parser registered as parserName.

matter.parse.yaml.inFile('./stuff.md', function(err, metadata, data) {
  if (!err) {
    console.log(metadata);
  };
});

matter.parsers.register(name, fn)

• name: The name of the parser. Once registered, the parser becomes a property of matter.parse.
• fn(data): The function to convert the extracted front matter string into a JSON object.
  • data: A string containing the extracted front matter data. matter tries clean the data up as best it can without breaking the format.

Registers a new front matter parser.

matter.parsers.register('odd', function(data) {
  var obj = {};
 
  data
    .split(',')
    .map(function(kv) {
      kv = kv.split('=');
      obj[kv[0]] = kv[1];
    });
 
  return obj;
});
 
console.log(matter.parse.odd('---\nfoo=bar,baz=qux\n---\n'));
// => {foo: 'bar', baz: 'qux'});

matter.parsers.unregister(name)

• name: The name of the parser to unregister.

Unregisters a parser.

matter.parsers.unregister('odd');

matter.parsers.defaults(overrides)

• overrides: An object containing the new defaults. matter uses the following defaults:
  • encoding (default='utf8'): The encoding to be used when reading files
  • ignore: A regex or string representing tokens to be ignored when extracting the front matter. Used to extract the front matter. The tokens ignored by default are //, /*, */, #.
  • indicator (default=/---/): A regex or string to use as the front matter head and tail indicators
  • indicators: An object of options to use for the front matter head and tail indicators:
    • head: A regex or string to use as the front matter's head indicator. Defaults to indicator's value.
    • tail: A regex or string to use as the front matter's tail indicator. Defaults to indicators's value

Sets new defaults for parsing.

matter.parsers.defaults({ignore: /!/g});

matter.parsers.defaults()

Returns a shallow copy of the parsing defaults.

console.log(matter.parsers.defaults());