matter

Flexible front matter parser

matter

Flexible front matter parser.

matter.yaml('---\nfoo: bar\n---');
// => {foo: bar} 
 
matter.yaml.inFile('./stuff.md', function(errdata) {
  // ... 
});
 
matter.json('---\n{"foo": "bar"}\n---');
// => {foo: bar} 
 
matter.json.inFile('./stuff.md', function(errdata) {
  // ... 
});
  • Parse front matters embedded in comments (or any configurable tokens)
  • Allow custom parsers to be plugged in
  • Keep the parsing as configurable as possible

Alias to matter.parse.yaml.

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

Alias to matter.parse.yaml.inFile.

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

Alias to matter.parse.json.

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

Alias to matter.parse.json.inFile.

matter.json.inFile('./stuff.md', function(errdata) {
  if (!err) {
    console.log(data);
  };
});
  • string: A string containing 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

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

console.log(matter.parse.yaml('---\nfoo: bar\n---'));
// => {foo: bar} 
  • 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, 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.
    • data: An object containing the extracted and parsed front matter data

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

matter.parse.yaml.inFile('./stuff.md', function(errdata) {
  if (!err) {
    console.log(data);
  };
});
  • 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'}); 
  • name: The name of the parser to unregister.

Unregisters a parser.

matter.parsers.unregister('odd');
  • 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});

Returns a shallow copy of the parsing defaults.

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