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.
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
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
One preset
or Matter
, or an array of them, defining all
the supported frontmatters (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 frommarker
(string
) — Character used for fences
Related
License
MIT © Titus Wormer