remark-frontmatter

remark-frontmatter

remark plugin to support frontmatter (YAML, TOML, and more).

Install

npm:

npm install remark-frontmatter

Use

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])

Support frontmatter (YAML, TOML, and more). 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 (such as, 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 from
• marker (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 fence
• fence (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
• anywhere (boolean, default: false) – if true, matter can be found anywhere in the document. If false (default), only matter at the start of the document is recognized

Example

For {type: 'yaml', marker: '-'}:

---
key: value
---

Yields:

{
  "type": "yaml",
  "value": "key: value"
}

For {type: 'custom', marker: {open: '<', close: '>'}}:

<<<
data
>>>

Yields:

{
  "type": "custom",
  "value": "data"
}

For {type: 'custom', fence: '+=+=+=+'}:

+=+=+=+
data
+=+=+=+

Yields:

{
  "type": "custom",
  "value": "data"
}

For {type: 'json', fence: {open: '{', close: '}'}}:

{
  "key": "value"
}

Yields:

{
  "type": "json",
  "value": "\"key\": \"value\""
}

Security

Use of remark-frontmatter does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS) attacks.

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

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer