mdast-util-frontmatter

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

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

* What is this?
* When to use this
* Install
* Use
* API
* frontmatterFromMarkdown(options?)
* frontmatterToMarkdown(options?)
* Info
* Matter
* Options
* Syntax
* Syntax tree
* Nodes
* Content model
* Types
* Compatibility
* Related
* Contribute
* License

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][mdast-util-from-markdown] (to support parsing
frontmatter in markdown into a syntax tree) and
[mdast-util-to-markdown][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][micromark-extension-frontmatter].

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

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

Install

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

``sh npm install mdast-util-frontmatter`

In Deno with [esm.sh][esmsh]:

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

In browsers with [esm.sh][esmsh]:

`html`

`Use`

Say our document example.md contains:

`markdown +++ title = "New Website" +++

`Other markdown`

…and our module example.js looks as follows:

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

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

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

console.log(tree)

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

console.log(out)`

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

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

`markdown +++ title = "New Website" +++

`Other markdown`

API

This package exports the identifiers [frontmatterFromMarkdown][api-frontmatter-from-markdown] and [frontmatterToMarkdown][api-frontmatter-to-markdown]. There is no default export.

`$3`

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

###### Parameters

* options ([Options][api-options], optional) — configuration

###### Returns

Extension for mdast-util-from-markdown([FromMarkdownExtension][from-markdown-extension]).

`$3`

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

###### Parameters

* options ([Options][api-options], optional) — configuration

###### Returns

Extension for mdast-util-to-markdown([ToMarkdownExtension][to-markdown-extension]).

`$3`

Structure of marker or fence (TypeScript type).

Same as [Info from micromark-extension-frontmatter][micromark-info].

`$3`

Structure of matter (TypeScript type).

Same as [Matter from micromark-extension-frontmatter][micromark-matter].

`$3`

Configuration (TypeScript type).

Same as [Options from micromark-extension-frontmatter][micromark-options].

`Syntax`

See [Syntax in micromark-extension-frontmatter][syntax].

`Syntax tree`

The following interfaces are added to [mdast][] by this utility.

`$3`

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

#### YAML

`idl interface YAML <: Literal { type: "yaml" }`

YAML ([Literal][dfn-literal]) represents a collection of metadata for the document in the YAML data serialization language.

YAML can be used where [frontmatter][dfn-frontmatter-content] content is expected. Its content is represented by itsvalue field.

For example, the following markdown:

`markdown --- foo: bar ---`

Yields:

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

`$3`

#### FrontmatterContent

`idl 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][term-tree], and can only exist as a [head][term-head].

#### FlowContent (frontmatter)

`idl type FlowContentFrontmatter = FrontmatterContent | FlowContent`

`Types`

This package is fully typed with [TypeScript][]. It exports the additional types [Info][api-info], [Matter][api-matter], and [Options][api-options].

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

`ts import type {Literal} from 'mdast'

interface Toml extends Literal { type: 'toml' }

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

`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,mdast-util-frontmatter@^2, compatible with Node.js 16.

This utility works with mdast-util-from-markdownversion 2+ andmdast-util-to-markdown version 2+.

`Related`

* [remark-frontmatter][remark-frontmatter] — remark plugin to support frontmatter * [micromark-extension-frontmatter][micromark-extension-frontmatter] — micromark extension to parse frontmatter

`Contribute`

See [contributing.md][contributing] in [syntax-tree/.github][health] for ways to get started. See [support.md`][support] for ways to get help.

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

License

[MIT][license] © [Titus Wormer][author]

[build-badge]: https://github.com/syntax-tree/mdast-util-frontmatter/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-frontmatter/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-frontmatter.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-frontmatter

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-frontmatter.svg

[downloads]: https://www.npmjs.com/package/mdast-util-frontmatter

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-frontmatter

[size]: https://bundlejs.com/?q=mdast-util-frontmatter

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[micromark]: https://github.com/micromark/micromark

[micromark-extension-frontmatter]: https://github.com/micromark/micromark-extension-frontmatter

[micromark-info]: https://github.com/micromark/micromark-extension-frontmatter#info

[micromark-matter]: https://github.com/micromark/micromark-extension-frontmatter#matter

[micromark-options]: https://github.com/micromark/micromark-extension-frontmatter#options

[syntax]: https://github.com/micromark/micromark-extension-frontmatter#syntax

[dfn-literal]: https://github.com/syntax-tree/mdast#literal

[term-tree]: https://github.com/syntax-tree/unist#tree

[term-head]: https://github.com/syntax-tree/unist#head

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[dfn-frontmatter-content]: #frontmattercontent

[api-frontmatter-from-markdown]: #frontmatterfrommarkdownoptions

[api-frontmatter-to-markdown]: #frontmattertomarkdownoptions

[api-info]: #info

[api-matter]: #matter

[api-options]: #options

mdast-util-frontmatter

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

What is this?

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][micromark-extension-frontmatter].

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

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

Install

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

``sh npm install mdast-util-frontmatter`

In Deno with [esm.sh][esmsh]:

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

In browsers with [esm.sh][esmsh]:

`html`

`Use`

Say our document example.md contains:

`markdown +++ title = "New Website" +++

`Other markdown`

…and our module example.js looks as follows:

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

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

console.log(tree)

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

console.log(out)`

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

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

`markdown +++ title = "New Website" +++

`Other markdown`

API

This package exports the identifiers [frontmatterFromMarkdown][api-frontmatter-from-markdown] and [frontmatterToMarkdown][api-frontmatter-to-markdown]. There is no default export.

`$3`

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

###### Parameters

* options ([Options][api-options], optional) — configuration

###### Returns

Extension for mdast-util-from-markdown([FromMarkdownExtension][from-markdown-extension]).

`$3`

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

###### Parameters

* options ([Options][api-options], optional) — configuration

###### Returns

Extension for mdast-util-to-markdown([ToMarkdownExtension][to-markdown-extension]).

`$3`

Structure of marker or fence (TypeScript type).

Same as [Info from micromark-extension-frontmatter][micromark-info].

`$3`

Structure of matter (TypeScript type).

Same as [Matter from micromark-extension-frontmatter][micromark-matter].

`$3`

Configuration (TypeScript type).

Same as [Options from micromark-extension-frontmatter][micromark-options].

`Syntax`

See [Syntax in micromark-extension-frontmatter][syntax].

`Syntax tree`

The following interfaces are added to [mdast][] by this utility.

`$3`

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

#### YAML

`idl interface YAML <: Literal { type: "yaml" }`

YAML ([Literal][dfn-literal]) represents a collection of metadata for the document in the YAML data serialization language.

YAML can be used where [frontmatter][dfn-frontmatter-content] content is expected. Its content is represented by itsvalue field.

For example, the following markdown:

`markdown --- foo: bar ---`

Yields:

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

`$3`

#### FrontmatterContent

`idl 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][term-tree], and can only exist as a [head][term-head].

#### FlowContent (frontmatter)

`idl type FlowContentFrontmatter = FrontmatterContent | FlowContent`

`Types`

This package is fully typed with [TypeScript][]. It exports the additional types [Info][api-info], [Matter][api-matter], and [Options][api-options].

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

`ts import type {Literal} from 'mdast'

interface Toml extends Literal { type: 'toml' }

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

`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,mdast-util-frontmatter@^2, compatible with Node.js 16.

This utility works with mdast-util-from-markdownversion 2+ andmdast-util-to-markdown version 2+.

`Related`

`Contribute`

See [contributing.md][contributing] in [syntax-tree/.github][health] for ways to get started. See [support.md`][support] for ways to get help.

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

License

[build-badge]: https://github.com/syntax-tree/mdast-util-frontmatter/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-frontmatter/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-frontmatter.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-frontmatter

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-frontmatter.svg

[downloads]: https://www.npmjs.com/package/mdast-util-frontmatter

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-frontmatter

[size]: https://bundlejs.com/?q=mdast-util-frontmatter

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[micromark]: https://github.com/micromark/micromark

[micromark-extension-frontmatter]: https://github.com/micromark/micromark-extension-frontmatter

[micromark-info]: https://github.com/micromark/micromark-extension-frontmatter#info

[micromark-matter]: https://github.com/micromark/micromark-extension-frontmatter#matter

[micromark-options]: https://github.com/micromark/micromark-extension-frontmatter#options

[syntax]: https://github.com/micromark/micromark-extension-frontmatter#syntax

[dfn-literal]: https://github.com/syntax-tree/mdast#literal

[term-tree]: https://github.com/syntax-tree/unist#tree

[term-head]: https://github.com/syntax-tree/unist#head

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[dfn-frontmatter-content]: #frontmattercontent

[api-frontmatter-from-markdown]: #frontmatterfrommarkdownoptions

[api-frontmatter-to-markdown]: #frontmattertomarkdownoptions

[api-info]: #info

[api-matter]: #matter

[api-options]: #options

mdast-util-frontmatter

mdast-util-frontmatter

Contents

What is this?

When to use this

Install

Use

Other markdown

Other markdown

API

$3

$3

$3

$3

$3

Syntax

Syntax tree

$3

$3

Types

Compatibility

Related

Contribute

License

mdast-util-frontmatter

mdast-util-frontmatter

Contents

What is this?

When to use this

Install

Use

Other markdown

Other markdown

API

$3

$3

$3

$3

$3

Syntax

Syntax tree

$3

$3

Types

Compatibility

Related

Contribute

License

`Use`

`Other markdown`

`Other markdown`

`$3`

`$3`

`$3`

`$3`

`$3`

`Syntax`

`Syntax tree`

`$3`

`$3`

`Types`

`Compatibility`

`Related`

`Contribute`

`Use`

`Other markdown`

`Other markdown`

`$3`

`$3`

`$3`

`$3`

`$3`

`Syntax`

`Syntax tree`

`$3`

`$3`

`Types`

`Compatibility`

`Related`

`Contribute`