matter

Flexible front matter parser

npm install matter
56 downloads in the last week
66 downloads in the last month

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());
npm loves you