delimiter seperated front matter parser / parser creator

Usage no npm install needed!

<script type="module">
  import dsfm from 'https://cdn.skypack.dev/dsfm';



Parse documents containing delimiter-separated front-matter

Build Status CircleCI Coverage Status


$ npm install --save dsfm


The simplest use case is to parse documents containing yaml front-matter:

const parser = require('dsfm').yaml;

var post = parser('---\ntitle: abc\n---\npost');
// => {attributes: {title: 'abc'}, body: 'post'}

or json front-matter:

const parser = require('dsfm').json;

const post = jsonfm('{{{\ntitle: abc\n}}}\npost');
// => {attributes: {title: 'abc'}, body: 'post'}

This can also generate custom document parsers, and parse streams of text (see below).

Note: So far as I know, there is no specification for front-matter (yaml or otherwise). This modules 'spec' defines front-matter as a block of text at the beginning of a string seperated by two delimiters, each on their own line. The opening delimiter must be the first thing in the string. The closing delimiter must be immediately followed by a newline character (or the end of the string).


dsfm(delimiters, [loader])

Constructs a new front-matter parser. See parser documentation below.


Type: string|array

The delimter(s) used for front-matter. Where both delims are the same you can use a string, such as '---'. If the opening and closing delims are different, use an array such as ['{{{', '}}}']

Note: The string(s) you provide will have any RegExp tokens escaped internally, so if you need to use backslashes inside delimiters, they must be escaped with another backslash. For example, the delimiter \fm\ should be supplied as \\fm\\


Type: function

An optional function to transform the front-matter after it is extracted. For example, dsfm.yaml() uses js-yamls's safeload and dsfm.json() uses JSON.parse().



Type: string

Parses the supplied doc and returns a content object of form { attributes: ..., body: ... }. If no front-matter is present, arrtibutes will be null and body body will contain the original string. Where the whole document is a front-matter block, attributes will be populated and the content will be an empty string ''.



Type: string

Test for the presence of front-matter in doc


Returns a through / transform stream for parsing streaming documents. The stream will emit a single attributes event then start emitted data containing the document body.

var fs = require('fs');
var yamlfm = require('dsfm').yaml;

var post = fs.createReadStream('./post.md')

post.on('attributes', function(attr) {

If no front-matter is present, the attributes payload will be null.


A parser for strings containing yaml front-matter, delimited by '---' and '---'. Generated internally using dsfm('---', yaml.safeLoad). It also implements the test(doc) and through() methods.


A parser for strings containing json front-matter, delimited by '{{{' and '}}}'. Generated internally using:

dsfm(['{{{', '}}}'], function (str) {
  return JSON.parse('{' + str + '}');

It also implements the test(doc) and through() methods.

Note: json front-matter is a set of object key-value pairs. Values may themselves be objects or arrays nested however deeply, but at the top level, it must be an object (not an array).


MIT © 2016-2107, axdg (axdg@dfant.asia)