remark-frontmatter

*   [`unified().use(remarkFrontmatter[, options])`](#unifieduseremarkfrontmatter-options)
*   [`Options`](#options)

*   [Example: different markers and fences](#example-different-markers-and-fences)
*   [Example: frontmatter as metadata](#example-frontmatter-as-metadata)
*   [Example: frontmatter in MDX](#example-frontmatter-in-mdx)

When should I use this?

Install

npm install remark-frontmatter

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

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

Use

+++
layout = "solar-system"
+++

# Jupiter

import remarkFrontmatter from 'remark-frontmatter'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
import {read} from 'to-vfile'

const file = await unified()
  .use(remarkParse)
  .use(remarkStringify)
  .use(remarkFrontmatter, ['yaml', 'toml'])
  .use(function () {
    return function (tree) {
      console.dir(tree)
    }
  })
  .process(await read('example.md'))

console.log(String(file))

{
  type: 'root',
  children: [
    {type: 'toml', value: 'layout = "solar-system"', position: [Object]},
    {type: 'heading', depth: 1, children: [Array], position: [Object]}
  ],
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 6, column: 1, offset: 43}
  }
}

+++
layout = "solar-system"
+++

# Jupiter

API

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

Parameters

• options (Optionsapi-options, default: 'yaml')

— configuration

Returns

Notes

Options

Type

type Options = Array<Matter | Preset> | Matter | Preset

/**
 * Sequence.
 *
 * Depending on how this structure is used, it reflects a marker or a fence.
 */
export type Info = {
  /**
   * Closing.
   */
  close: string
  /**
   * Opening.
   */
  open: string
}

/**
 * Fence configuration.
 */
type FenceProps = {
  /**
   * Complete fences.
   *
   * This can be used when fences contain different characters or lengths
   * other than 3.
   * Pass `open` and `close` to interface to specify different characters for opening and
   * closing fences.
   */
  fence: Info | string
  /**
   * If `fence` is set, `marker` must not be set.
   */
  marker?: never
}

/**
 * Marker configuration.
 */
type MarkerProps = {
  /**
   * Character repeated 3 times, used as complete fences.
   *
   * For example the character `'-'` will result in `'---'` being used as the
   * fence
   * Pass `open` and `close` to specify different characters for opening and
   * closing fences.
   */
  marker: Info | string
  /**
   * If `marker` is set, `fence` must not be set.
   */
  fence?: never
}

/**
 * Fields describing a kind of matter.
 *
 * > 👉 **Note**: using `anywhere` is a terrible idea.
 * > It’s called frontmatter, not matter-in-the-middle or so.
 * > This makes your markdown less portable.
 *
 * > 👉 **Note**: `marker` and `fence` are mutually exclusive.
 * > If `marker` is set, `fence` must not be set, and vice versa.
 */
type Matter = (MatterProps & FenceProps) | (MatterProps & MarkerProps)

/**
 * Fields describing a kind of matter.
 */
type MatterProps = {
  /**
   * Node type to tokenize as.
   */
  type: string
  /**
   * Whether matter can be found anywhere in the document, normally, only matter
   * at the start of the document is recognized.
   *
   * > 👉 **Note**: using this is a terrible idea.
   * > It’s called frontmatter, not matter-in-the-middle or so.
   * > This makes your markdown less portable.
   */
  anywhere?: boolean | null | undefined
}

/**
 * Known name of a frontmatter style.
 */
type Preset = 'toml' | 'yaml'

Examples

Example: different markers and fences

```yaml

key: value

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:

```text
<<<
data
>>>

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

{
  "key": "value"
}

Example: frontmatter as metadata

/**
 * @typedef {import('unist').Node} Node
 * @typedef {import('vfile').VFile} VFile
 */

import {matter} from 'vfile-matter'

/**
 * Parse YAML frontmatter and expose it at `file.data.matter`.
 *
 * @returns
 *   Transform.
 */
export default function myUnifiedPluginHandlingYamlMatter() {
  /**
   * Transform.
   *
   * @param {Node} tree
   *   Tree.
   * @param {VFile} file
   *   File.
   * @returns {undefined}
   *   Nothing.
   */
  return function (tree, file) {
    matter(file)
  }
}

```markdown

key: value

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

```js
import remarkParse from 'remark-parse'
import remarkFrontmatter from 'remark-frontmatter'
import remarkStringify from 'remark-stringify'
import {read} from 'to-vfile'
import {unified} from 'unified'
import myUnifiedPluginHandlingYamlMatter from './my-unified-plugin-handling-yaml-matter.js'

const file = await unified()
  .use(remarkParse)
  .use(remarkStringify)
  .use(remarkFrontmatter)
  .use(myUnifiedPluginHandlingYamlMatter)
  .process(await read('example.md'))

console.log(file.data.matter) // => {key: 'value'}

Example: frontmatter in MDX

```mdx

key: value

This plugin can be used as follows:

```js
import {compile} from '@mdx-js/mdx'
import remarkFrontmatter from 'remark-frontmatter'
import remarkMdxFrontmatter from 'remark-mdx-frontmatter'
import {read, write} from 'to-vfile'

const file = await compile(await read('example.mdx'), {
  remarkPlugins: [remarkFrontmatter, [remarkMdxFrontmatter, {name: 'matter'}]]
})
file.path = 'output.js'
await write(file)

const mod = await import('./output.js')
console.log(mod.matter) // => {key: 'value'}

Authoring

HTML

CSS

Syntax

Syntax tree

Types

import type {Data, Literal} from 'mdast'

interface Toml extends Literal {
  type: 'toml'
  data?: TomlData
}

declare module 'mdast' {
  interface FrontmatterContentMap {
    // Allow using TOML nodes defined by `remark-frontmatter`.
    toml: Toml
  }
}

Compatibility

Security

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

License