Project: syntax-tree/mdast-util-frontmatter

Package: mdast-util-frontmatter@1.0.0

  1. Dependents: 0
  2. mdast extension to parse and serialize frontmatter (YAML, TOML, etc)
  1. markdown 162
  2. util 146
  3. utility 142
  4. unist 132
  5. mdast 91
  6. mdast-util 31
  7. gfm 21
  8. markup 19
  9. frontmatter 7
  10. yaml 7
  11. toml 4


Build Coverage Downloads Size Sponsors Backers Chat

mdast extensions to parse and serialize frontmatter (YAML, TOML, and more).


What is this?

This package contains two extensions that add support for frontmatter syntax as often used in markdown to mdast. These extensions plug into mdast-util-from-markdown (to support parsing frontmatter in markdown into a syntax tree) and mdast-util-to-markdown (to support serializing frontmatter in syntax trees to markdown).

Frontmatter is a metadata format in front of the content. It’s typically written in YAML and is often used with markdown. Frontmatter does not work everywhere so it makes markdown less portable.

These extensions follow how GitHub handles frontmatter. GitHub only supports YAML frontmatter, but these extensions also support different flavors (such as TOML).

When to use this

You can use these extensions when you are working with mdast-util-from-markdown and mdast-util-to-markdown already.

When working with mdast-util-from-markdown, you must combine this package with micromark-extension-frontmatter.

When you don’t need a syntax tree, you can use micromark directly with micromark-extension-frontmatter.

All these packages are used remark-frontmatter, which focusses on making it easier to transform content by abstracting these internals away.


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

npm install mdast-util-frontmatter

In Deno with esm.sh:

import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@1'

In browsers with esm.sh:

<script type="module">
  import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@1?bundle'


Say our document example.md contains:

title = "New Website"

# Other markdown

…and our module example.js looks as follows:

import fs from 'node:fs/promises'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {frontmatter} from 'micromark-extension-frontmatter'
import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'mdast-util-frontmatter'

const doc = await fs.readFile('example.md')

const tree = fromMarkdown(doc, {
  extensions: [frontmatter(['yaml', 'toml'])],
  mdastExtensions: [frontmatterFromMarkdown(['yaml', 'toml'])]


const out = toMarkdown(tree, {extensions: [frontmatterToMarkdown(['yaml', 'toml'])]})


…now running node example.js yields (positional info removed for brevity):

  type: 'root',
  children: [
    {type: 'toml', value: 'title = "New Website"'},
      type: 'heading',
      depth: 1,
      children: [{type: 'text', value: 'Other markdown'}]
title = "New Website"

# Other markdown


This package exports the identifiers frontmatterFromMarkdown and frontmatterToMarkdown. There is no default export.


Create an extension for mdast-util-from-markdown.


Extension for mdast-util-from-markdown (FromMarkdownExtension).


Create an extension for mdast-util-to-markdown.


Extension for mdast-util-to-markdown (ToMarkdownExtension).


Structure of marker or fence (TypeScript type).

Same as Info from micromark-extension-frontmatter.


Structure of matter (TypeScript type).

Same as Matter from micromark-extension-frontmatter.


Configuration (TypeScript type).

Same as Options from micromark-extension-frontmatter.


See Syntax in micromark-extension-frontmatter.

Syntax tree

The following interfaces are added to mdast by this utility.


👉 Note: other nodes are not enabled by default, but when passing options to enable them, they work the same as YAML.


interface YAML <: Literal {
  type: "yaml"

YAML (Literal) represents a collection of metadata for the document in the YAML data serialization language.

YAML can be used where frontmatter content is expected. Its content is represented by its value field.

For example, the following markdown:

foo: bar


{type: 'yaml', value: 'foo: bar'}

Content model


type FrontmatterContent = YAML

Frontmatter content represent out-of-band information about the document.

If frontmatter is present, it must be limited to one node in the tree, and can only exist as a head.

FlowContent (frontmatter)

type FlowContentFrontmatter = FrontmatterContent | FlowContent


This package is fully typed with TypeScript. It exports the additional types Info, Matter, and Options.

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

import type {Literal} from 'mdast'

interface Toml extends Literal {
  type: 'toml'

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


Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+ and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

These extensions works with mdast-util-from-markdown version 1+ and mdast-util-to-markdown version 1+.


See contributing.md in syntax-tree/.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.


MIT © Titus Wormer