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 either a marker
or a fence
:
type
(string
) — Node type to parse to in mdast and compile frommarker
(string
or {open: string, close: string}
) — Character used
to construct fences. By providing an object with open
and close
.
different characters can be used for opening and closing fences. For
example the character '-'
will result in '---'
being used as the fencefence
(string
or {open: string, close: string}
) — String used as
the complete fence. By providing an object with open
and close
different values can be used for opening and closing fences. This can be
used too if fences contain different characters or lengths other than 3
Example
For {type: 'yaml', marker: '-'}
:
---
key: value
---
Yields:
{
"type": "yaml",
"value": "key: value"
}
Example
For {type: 'custom', marker: {open: '<', close: '>'}}
:
<<<
data
>>>
Yields:
{
"type": "custom",
"value": "data"
}
Example
For {type: 'custom', fence: '+=+=+=+'}
:
+=+=+=+
data
+=+=+=+
Yields:
{
"type": "custom",
"value": "dats"
}
Example
For {type: 'json', fence: {open: '{', close: '}'}}
:
{
"key": "value"
}
Yields:
{
"type": "json",
"value": "\"key\": \"value\""
}
Related
License
MIT © Titus Wormer