remark-frontmatter

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

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • unified().use(remarkFrontmatter[, options])
  • Options
• Examples
  • Example: different markers and fences
  • Example: frontmatter as metadata
  • Example: frontmatter in MDX
• Authoring
• HTML
• CSS
• Syntax
• Syntax tree
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a unified (remark) plugin to add support for YAML, TOML, and other frontmatter.

Frontmatter is a metadata format in front of the content. It’s typically written in YAML and is often used with markdown.

This plugin follow how GitHub handles frontmatter. GitHub only supports YAML frontmatter, but this plugin also supports different flavors (such as TOML).

When should I use this?

You can use frontmatter when you want authors, that have some markup experience, to configure where or how the content is displayed or supply metadata about content, and know that the markdown is only used in places that support frontmatter. A good example use case is markdown being rendered by (static) site generators.

If you just want to turn markdown into HTML (with maybe a few extensions such as frontmatter), we recommend micromark with micromark-extension-frontmatter instead. If you don’t use plugins and want to access the syntax tree, you can use mdast-util-from-markdown with mdast-util-frontmatter.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

1npm install remark-frontmatter

In Deno with esm.sh:

1import remarkFrontmatter from 'https://esm.sh/remark-frontmatter@5'

In browsers with esm.sh:

1<script type="module">
2  import remarkFrontmatter from 'https://esm.sh/remark-frontmatter@5?bundle'
3</script>

Use

Say our document example.md contains:

1+++
2layout = "solar-system"
3+++
4
5# Jupiter

…and our module example.js contains:

1import remarkFrontmatter from 'remark-frontmatter'
2import remarkParse from 'remark-parse'
3import remarkStringify from 'remark-stringify'
4import {unified} from 'unified'
5import {read} from 'to-vfile'
6
7const file = await unified()
8  .use(remarkParse)
9  .use(remarkStringify)
10  .use(remarkFrontmatter, ['yaml', 'toml'])
11  .use(function () {
12    return function (tree) {
13      console.dir(tree)
14    }
15  })
16  .process(await read('example.md'))
17
18console.log(String(file))

…then running node example.js yields:

1{
2  type: 'root',
3  children: [
4    {type: 'toml', value: 'layout = "solar-system"', position: [Object]},
5    {type: 'heading', depth: 1, children: [Array], position: [Object]}
6  ],
7  position: {
8    start: {line: 1, column: 1, offset: 0},
9    end: {line: 6, column: 1, offset: 43}
10  }
11}

1+++
2layout = "solar-system"
3+++
4
5# Jupiter

API

This package exports no identifiers. The default export is remarkFrontmatter.

unified().use(remarkFrontmatter[, options])

Add support for frontmatter.

Parameters

• options (Options, default: 'yaml') — configuration

Returns

Nothing (undefined).

Notes

Doesn’t parse the data inside them: create your own plugin to do that.

Options

Configuration (TypeScript type).

Type

1type Options = Array<Matter | Preset> | Matter | Preset
2
3/**
4 * Sequence.
5 *
6 * Depending on how this structure is used, it reflects a marker or a fence.
7 */
8export type Info = {
9  /**
10   * Closing.
11   */
12  close: string
13  /**
14   * Opening.
15   */
16  open: string
17}
18
19/**
20 * Fence configuration.
21 */
22type FenceProps = {
23  /**
24   * Complete fences.
25   *
26   * This can be used when fences contain different characters or lengths
27   * other than 3.
28   * Pass `open` and `close` to interface to specify different characters for opening and
29   * closing fences.
30   */
31  fence: Info | string
32  /**
33   * If `fence` is set, `marker` must not be set.
34   */
35  marker?: never
36}
37
38/**
39 * Marker configuration.
40 */
41type MarkerProps = {
42  /**
43   * Character repeated 3 times, used as complete fences.
44   *
45   * For example the character `'-'` will result in `'---'` being used as the
46   * fence
47   * Pass `open` and `close` to specify different characters for opening and
48   * closing fences.
49   */
50  marker: Info | string
51  /**
52   * If `marker` is set, `fence` must not be set.
53   */
54  fence?: never
55}
56
57/**
58 * Fields describing a kind of matter.
59 *
60 * > 👉 **Note**: using `anywhere` is a terrible idea.
61 * > It’s called frontmatter, not matter-in-the-middle or so.
62 * > This makes your markdown less portable.
63 *
64 * > 👉 **Note**: `marker` and `fence` are mutually exclusive.
65 * > If `marker` is set, `fence` must not be set, and vice versa.
66 */
67type Matter = (MatterProps & FenceProps) | (MatterProps & MarkerProps)
68
69/**
70 * Fields describing a kind of matter.
71 */
72type MatterProps = {
73  /**
74   * Node type to tokenize as.
75   */
76  type: string
77  /**
78   * Whether matter can be found anywhere in the document, normally, only matter
79   * at the start of the document is recognized.
80   *
81   * > 👉 **Note**: using this is a terrible idea.
82   * > It’s called frontmatter, not matter-in-the-middle or so.
83   * > This makes your markdown less portable.
84   */
85  anywhere?: boolean | null | undefined
86}
87
88/**
89 * Known name of a frontmatter style.
90 */
91type Preset = 'toml' | 'yaml'

Examples

Example: different markers and fences

Here are a couple of example of different matter objects and what frontmatter they match.

To match frontmatter with the same opening and closing fence, namely three of the same markers, use for example {type: 'yaml', marker: '-'}, which matches:

1---
2key: value
3---

To match frontmatter with different opening and closing fences, which each use three different markers, use for example {type: 'custom', marker: {open: '<', close: '>'}}, which matches:

1<<<
2data
3>>>

To match frontmatter with the same opening and closing fences, which both use the same custom string, use for example {type: 'custom', fence: '+=+=+=+'}, which matches:

1+=+=+=+
2data
3+=+=+=+

To match frontmatter with different opening and closing fences, which each use different custom strings, use for example {type: 'json', fence: {open: '{', close: '}'}}, which matches:

1{
2  "key": "value"
3}

Example: frontmatter as metadata

This plugin handles the syntax of frontmatter in markdown. It does not parse that frontmatter as say YAML or TOML and expose it somewhere.

In unified, there is a place for metadata about files: file.data. For frontmatter specifically, it’s customary to expose parsed data at file.data.matter.

We can make a plugin that does this. This example uses the utility vfile-matter, which is specific to YAML. To support other data languages, look at this utility for inspiration.

my-unified-plugin-handling-yaml-matter.js:

1/**
2 * @typedef {import('unist').Node} Node
3 * @typedef {import('vfile').VFile} VFile
4 */
5
6import {matter} from 'vfile-matter'
7
8/**
9 * Parse YAML frontmatter and expose it at `file.data.matter`.
10 *
11 * @returns
12 *   Transform.
13 */
14export default function myUnifiedPluginHandlingYamlMatter() {
15  /**
16   * Transform.
17   *
18   * @param {Node} tree
19   *   Tree.
20   * @param {VFile} file
21   *   File.
22   * @returns {undefined}
23   *   Nothing.
24   */
25  return function (tree, file) {
26    matter(file)
27  }
28}

…with an example markdown file example.md:

1---
2key: value
3---
4
5# Venus

…and using the plugin with an example.js containing:

1import remarkParse from 'remark-parse'
2import remarkFrontmatter from 'remark-frontmatter'
3import remarkStringify from 'remark-stringify'
4import {read} from 'to-vfile'
5import {unified} from 'unified'
6import myUnifiedPluginHandlingYamlMatter from './my-unified-plugin-handling-yaml-matter.js'
7
8const file = await unified()
9  .use(remarkParse)
10  .use(remarkStringify)
11  .use(remarkFrontmatter)
12  .use(myUnifiedPluginHandlingYamlMatter)
13  .process(await read('example.md'))
14
15console.log(file.data.matter) // => {key: 'value'}

Example: frontmatter in MDX

MDX has the ability to export data from it, where markdown does not. When authoring MDX, you can write export statements and expose arbitrary data through them. It is also possible to write frontmatter, and let a plugin turn those into export statements.

To automatically turn frontmatter into export statements, use remark-mdx-frontmatter.

With an example.mdx as follows:

1---
2key: value
3---
4
5# Mars

This plugin can be used as follows:

1import {compile} from '@mdx-js/mdx'
2import remarkFrontmatter from 'remark-frontmatter'
3import remarkMdxFrontmatter from 'remark-mdx-frontmatter'
4import {read, write} from 'to-vfile'
5
6const file = await compile(await read('example.mdx'), {
7  remarkPlugins: [remarkFrontmatter, [remarkMdxFrontmatter, {name: 'matter'}]]
8})
9file.path = 'output.js'
10await write(file)
11
12const mod = await import('./output.js')
13console.log(mod.matter) // => {key: 'value'}

Authoring

When authoring markdown with frontmatter, it’s recommended to use YAML frontmatter if possible. While YAML has some warts, it works in the most places, so using it guarantees the highest chance of portability.

In certain ecosystems, other flavors are widely used. For example, in the Rust ecosystem, TOML is often used. In such cases, using TOML is an okay choice.

When possible, do not use other types of frontmatter, and do not allow frontmatter anywhere.

HTML

Frontmatter does not relate to HTML elements. It is typically stripped, which is what remark-rehype does.

CSS

This package does not relate to CSS.

Syntax

See Syntax in micromark-extension-frontmatter.

Syntax tree

See Syntax tree in mdast-util-frontmatter.

Types

This package is fully typed with TypeScript. It exports the additional type Options.

The YAML node type is supported in @types/mdast by default. To add other node types, register them by adding them to FrontmatterContentMap:

1import type {Data, Literal} from 'mdast'
2
3interface Toml extends Literal {
4  type: 'toml'
5  data?: TomlData
6}
7
8declare module 'mdast' {
9  interface FrontmatterContentMap {
10    // Allow using TOML nodes defined by `remark-frontmatter`.
11    toml: Toml
12  }
13}

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, remark-frontmatter@^5, compatible with Node.js 16.

This plugin works with unified 6+ and remark 13+.

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-yaml-config — configure remark from YAML configuration
• remark-gfm — support GFM (autolink literals, footnotes, strikethrough, tables, tasklists)
• remark-mdx — support MDX (ESM, JSX, expressions)
• remark-directive — support directives
• remark-math — support math

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