Skip to content
Simple front matter parser that parses YAML, JSON and TOML
Branch: master
Clone or download
Pull request Compare This branch is 49 commits ahead, 80 commits behind jonschlinkert:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
preliminaries-parser-json5
preliminaries-parser-toml
preliminaries-parser-yaml
preliminaries
.eslintrc.json
.gitignore
.travis.yml
CONTRIBUTING.md
LICENSE
Makefile
README.md

README.md

preliminaries Linux Build Status npm version

Simple front matter parser for Markdown that supports JSON, YAML, TOML and custom parsers.

Now with JSON5 support!

Forked from the excellent jonschlinkert/gray-matter, prelimimaries strips things down and makes the YAML and TOML parsers entirely optional, as well as supporting stringifying languages other than YAML.

Improved parsing and auto-detection of languages supports JSON front matter with { and } plain delimiters and TOML with +++ delimiters as used in Hugo.

Dependency

npm

npm install --save preliminaries
# Optional
npm install --save preliminaries-parser-yaml
npm install --save preliminaries-parser-toml
npm install --save preliminaries-parser-json5

yarn

yarn add preliminaries
# Optional
yarn add preliminaries-parser-yaml
yarn add preliminaries-parser-toml
yarn add preliminaries-parser-json5

Using preliminaries

Preliminaries(register: boolean): Preliminaries

Registers any default parsers (currently only JSON) for their default languages.

PreliminariesParser(register: boolean): PreliminariesParser

Registers the parser for it's default language.

Load preliminaries and some parsers and register the parsers for their default languages:

var preliminaries = require('preliminaries')(true);
require('preliminaries-parser-yaml')(true);
require('preliminaries-parser-toml')(true);

Load preliminaries and some parsers without registering any parsers:

var preliminaries = require('preliminaries');
var tomlParser = require('preliminaries-parser-yaml');
var yamlParser = require('preliminaries-parser-toml');

Preliminaries.parse(str: string, options?: PreliminariesOptions): any

Parse some JSON front matter:

preliminaries.parse('{\n"name":"Joseph"\n}\nContent')
// Returns
{
  data: {name: 'Joseph'},
  content: 'Content'
}

or YAML:

preliminaries.parse('---\nname: Joseph\n---\nContent')
// Returns
{
  data: {name: 'Joseph'},
  content: 'Content'
}

and even TOML:

preliminaries.parse('+++\nname = "Joseph"\n+++\nContent')
// Returns
{
  data: {name: 'Joseph'},
  content: 'Content'
}

It can automatically detect any language embedded after the first delimiter such as ---yaml or ---json, as well standard delimiters for languages such as +++ for TOML or { and } for JSON.

Use custom delimiters:

preliminaries.parse('~~~\nname: Joseph\n~~~\nContent', {lang: 'yaml', delims: '~~~'})
// Returns
{
  data: {name: 'Joseph'},
  content: 'Content'
}

with JSON as well!

preliminaries.parse('~~~\n{\n"name":"Joseph"\n}\n~~~\nContent', {lang: 'json', delims: '~~~'})
// Returns
{
  data: {name: 'Joseph'},
  content: 'Content'
}

Preliminaries.stringify(str: string, data: Object, options?: PreliminariesOptions): string

Stringify a content string and front matter JavaScript object:

preliminaries.stringify('Content', {name: 'Joseph'})
// Returns
---json
{
"name":"Joseph"
}
---
Content

with standard JSON delimiters:

preliminaries.stringify('Content', {name: 'Joseph'}, {stringifyUseParserDelims: true})
// Returns
{
"name":"Joseph"
}
Content

or YAML front matter:

preliminaries.stringify('Content', {name: 'Joseph'}, {lang: 'yaml', stringifyUseParserDelims: true})
// Returns
---
name: Joseph
---
Content

Stringify with custom delimiters:

preliminaries.stringify('Content', {name: 'Joseph'}, {lang: 'yaml', delims: '~~~'})
// Returns
~~~
name: Joseph
~~~
Content

Preliminaries.test(str: string, options?: PreliminariesOptions): boolean

Test whether a string contains front matter of any kind:

preliminaries.test('{\n"abc": "xyz"\n}');
preliminaries.test('---\nabc: xyz\n---');
preliminaries.test('+++\nabc = "xyz"\n+++');
preliminaries.test('~~~\nabc = "xyz"\n~~~');
// All return true

or front matter with particular delimiters:

preliminaries.test('---\nabc: xyz\n---', {delims: '~~~'});
// Returns false

Preliminaries.register(lang: string | string[], parser: PreliminariesParser): void

Register a parser for a new language:

preliminaries.register('xml', xmlParser);

for this to succeed no parser must be already registered for the language, and the opening delimiters of the parser must not match the opening delimiters of any parser currently registered (this would lead to ambiguous auto-detection of languages).

An error will be thrown if either of the above conditions are false. You can check if a parser can be registered with Preliminaries.registerable.

Preliminaries.unregister(lang: string | string[]): void

Unregister a previously registered parser:

preliminaries.unregister('json');

Preliminaries.registerable(lang: string | string[], parser: PreliminariesParser): boolean

Check if a parser can be registered for the language, or all languages if an array -- this returns `false if a parser is already registered for any of the languages, or if the opening delimiters of this parser match those of an already existing parser:

preliminaries.registerable('---', parser: myParser);

if this call returns true, a subsequent call to Preliminaries.register will succeed without error.

Preliminaries.registered(lang: string | string[]): boolean

Check if a parser is registered for a language:

preliminaries.registered('json');

or if one is registered for any of the languages:

preliminaries.registered(['json', 'yaml', 'toml']);

Note: a false result does not indicate a parser may be registered without error, just that one is not already registered for this language; use Preliminaries.registerable for that purpose.

Preliminaries.jsonParser: PreliminariesParser

The default JSON parser. Use it to register it for another language:

var preliminaries = require('preliminaries');
preliminaries.register('xyz', preliminaries.jsonParser)
preliminaries.parse('---xyz\n{\n"name":"Joseph"\n}\n---\nContent')
// Returns
{
  data: {name: 'Joseph'},
  content: 'Content'
}

Options

PreliminariesOptions.parser?: PreliminariesParser

Optionally provide a custom parser to use when parsing or stringifying.

PreliminariesOptions.lang?: string

The language the front matter is in.

Required when parsing if using custom delimiters or whenever stringifying to language other than JSON.

PreliminariesOptions.delims?: string | string[]

Custom delimiters.

A string (if start and end delimiters are the same), or an array of 2 elements containing the start and end delimiters.

PreliminariesOptions.stringifyIncludeLang?: boolean

Whether to output the front matter language the first delimiter.

If not set the language will be output when stringifying if a custom delimiters are not set with PreliminariesOptions.delims and PreliminariesOptions.stringifyUseParserDelims is not truthy.

PreliminariesOptions.stringifyUseParserDelims?: boolean

Whether to stringify using the default delimiters defined by the parser for the language, instead of the default ---lang format.

Creating parsers

Your parser should include preliminaries as a peerDependency in your package.json.

PreliminariesParser(register: boolean): PreliminariesParser

The root export of your parser should be a function that accepts a boolean value, if truthy you should register your parser for it's default language:

var preliminaries = require('preliminaries');

var myParser = function(register) {
  if (register) {
    preliminaries.register('abc', myParser);
  }
}

module.exports = myParser;

PreliminariesParser.parse(str: string, options?: PreliminariesOptions): any

Parse a front matter string without delimiters into a JavaScript object.

myParser.parse = function(str, options) {
  return {};
}

PreliminariesParser.stringify(data: Object, options?: PreliminariesOptions): string

Stringify a JavaScript front matter object into string without delimiters.

myParser.stringify = function(data, options) {
  return '';
}

PreliminariesParser.delims?: string | string[]

The default delimiters for the parser, used to auto-detect the language and parser to use and when stringifying with the stringifyUseParserDelims option.

A string (if start and end delimiters are the same), or an array of 2 elements containing the start and end delimiters.

myParser.delims = ['<', '>'];
You can’t perform that action at this time.