Skip to content
plugin to support frontmatter (YAML, TOML, and more)
JavaScript
Branch: master
Clone or download
Latest commit bc4a7f8 Jul 23, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Refactor comments Jun 16, 2019
test Refactor comments Jun 16, 2019
.editorconfig Initial commit Jul 20, 2017
.gitignore Add `yarn.lock` to `.gitignore` Aug 10, 2018
.npmrc Add `.npmrc` Aug 10, 2018
.prettierignore Refactor code-style Aug 10, 2018
.travis.yml
index.js Refactor code-style Aug 10, 2018
license Move `LICENSE` > `license` Sep 23, 2018
package.json Update dev-dependencies Jul 23, 2019
readme.md Add notes on security Jul 23, 2019

readme.md

remark-frontmatter

Build Coverage Downloads Size Sponsors Backers Chat

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 recognised.
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": "dats"
}

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

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, organisation, or community you agree to abide by its terms.

License

MIT © Titus Wormer

You can’t perform that action at this time.