remark-frontmatter

What is remark-frontmatter?

The remark-frontmatter package is a plugin for the remark processor that allows you to parse and manipulate frontmatter in Markdown files. Frontmatter is typically used to include metadata at the beginning of a Markdown document, often in YAML or TOML format.

What are remark-frontmatter's main functionalities?

Parsing YAML frontmatter

This feature allows you to parse YAML frontmatter in a Markdown file. The code sample demonstrates how to use the remark-frontmatter plugin to parse YAML frontmatter and process the Markdown content.

const remark = require('remark');
const frontmatter = require('remark-frontmatter');

const markdown = `---
title: Example Title
date: 2023-10-01
---

# Hello World
`;

remark()
  .use(frontmatter, ['yaml'])
  .process(markdown, function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Parsing TOML frontmatter

This feature allows you to parse TOML frontmatter in a Markdown file. The code sample demonstrates how to use the remark-frontmatter plugin to parse TOML frontmatter and process the Markdown content.

const remark = require('remark');
const frontmatter = require('remark-frontmatter');

const markdown = `+++
title = "Example Title"
date = "2023-10-01"
+++

# Hello World
`;

remark()
  .use(frontmatter, ['toml'])
  .process(markdown, function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Parsing multiple types of frontmatter

This feature allows you to parse multiple types of frontmatter (e.g., YAML and TOML) in a Markdown file. The code sample demonstrates how to use the remark-frontmatter plugin to parse both YAML and TOML frontmatter and process the Markdown content.

const remark = require('remark');
const frontmatter = require('remark-frontmatter');

const markdown = `---
title: Example Title
date: 2023-10-01
---

# Hello World
`;

remark()
  .use(frontmatter, ['yaml', 'toml'])
  .process(markdown, function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Other packages similar to remark-frontmatter

gray-matter

gray-matter is a popular package for parsing frontmatter from strings or files. It supports YAML, TOML, and JSON frontmatter. Compared to remark-frontmatter, gray-matter is more versatile as it can be used outside of the remark ecosystem and provides more features for handling frontmatter data.

front-matter

front-matter is a simple package for parsing YAML frontmatter from strings. It is lightweight and easy to use but does not support TOML or JSON frontmatter. Compared to remark-frontmatter, it is more limited in scope but can be a good choice for projects that only need to handle YAML frontmatter.

markdown-it-front-matter

markdown-it-front-matter is a plugin for the markdown-it parser that allows you to extract frontmatter from Markdown files. It supports YAML frontmatter and integrates well with the markdown-it ecosystem. Compared to remark-frontmatter, it is designed specifically for use with markdown-it rather than remark.

README

remark-frontmatter

Frontmatter (YAML, TOML, and more) support for remark.

Installation

npm:

npm install remark-frontmatter

Usage

Say we have the following file, example.md:

+++
title = "New Website"
+++

# Other markdown

And our script, example.js, looks as follows:

var vfile = require('to-vfile');
var report = require('vfile-reporter');
var unified = require('unified');
var parse = require('remark-parse');
var stringify = require('remark-stringify');
var frontmatter = require('remark-frontmatter');

unified()
  .use(parse)
  .use(stringify)
  .use(frontmatter, ['yaml', 'toml'])
  .use(logger)
  .process(vfile.readSync('example.md'), function (err, file) {
    console.log(String(file));
    console.error(report(err || file));
  });

function logger() {
  return console.dir;
}

Now, running node example yields:

{ type: 'root',
  children:
   [ { type: 'toml',
       value: 'title = "New Website"',
       position: [Object] },
     { type: 'heading',
       depth: 1,
       children: [Array],
       position: [Object] } ],
  position: [Object] }

example.md: no issues found
+++
title = "New Website"
+++

# Other markdown

API

remark.use(frontmatter[, options])

Adds tokenizers if the processor is configured with remark-parse, and visitors if configured with remark-stringify.

If you are parsing from a different syntax, or compiling to a different syntax (e.g., remark-man) your custom nodes may not be supported.

options

An optional configuration array defining all the supported frontmatters (Array.<preset|Matter>?, default: ['yaml']).

preset

Either 'yaml' or 'toml':

• 'yaml' — matter defined as {type: 'yaml', marker: '-'}
• 'toml' — matter defined as {type: 'toml', marker: '+'}

Matter

An object with a type and a marker:

• type (string) — Node type to parse to in mdast and compile from
• marker (string) — Character used for fences

Related

• remark-github — Auto-link references like in GitHub issues, PRs, and comments
• remark-math — Math support
• remark-yaml-config — Configure remark from YAML configuration

License

MIT © Titus Wormer