mdast-util-frontmatter
mdast extensions to parse and serialize frontmatter (YAML, TOML, and more).
Contents
What is this?
This package contains extensions that add support for the frontmatter syntax enabled by GitHub and many other places to mdast-util-from-markdown
and mdast-util-to-markdown
.
Frontmatter is a metadata format in front of content. It’s typically written in YAML and is often used with markdown. Frontmatter does not work everywhere so it makes markdown less portable.
When to use this
These tools are all rather low-level. In most cases, you’d want to use remark-frontmatter
with remark instead.
When working with mdast-util-from-markdown
, you must combine this package with micromark-extension-frontmatter
.
Install
This package is ESM only. In Node.js (version 12.20+, 14.14+, or 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'
</script>
Use
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'])]
})
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):
{
type: 'root',
children: [
{type: 'toml', value: 'title = "New Website"'},
{
type: 'heading',
depth: 1,
children: [{type: 'text', value: 'Other markdown'}]
}
]
}
+++
title = "New Website"
+++
# Other markdown
API
This package exports the identifiers frontmatterFromMarkdown
and frontmatterToMarkdown
. There is no default export.
frontmatterFromMarkdown(options?)
Function that can be called to get an extension for mdast-util-from-markdown
.
options
Configuration (optional). Same as micromark-extension-frontmatter
.
frontmatterToMarkdown(options?)
Function that can be called to get an extension for mdast-util-to-markdown
.
options
Configuration (optional). Same as micromark-extension-frontmatter
.
Syntax tree
The following interfaces are added to mdast by this utility.
Nodes
👉 Note: other nodes are not enabled by default, but when passing options to enable them, they work the same as YAML.
YAML
interface YAML <: Literal {
type: "yaml"
}
YAML (Literal) represents a collection of metadata for the document in the YAML data serialisation 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
---
Yields:
{type: 'yaml', value: 'foo: bar'}
Content model
FrontmatterContent
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
Types
This package is fully typed with TypeScript. It exports the additional types Options
, Matter
, and Info
.
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
}
}
Compatibility
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.
This plugin works with mdast-util-from-markdown
version 1+ and mdast-util-to-markdown
version 1+.
Related
remarkjs/remark-frontmatter
— remark plugin to support frontmattermicromark/micromark-extension-frontmatter
— micromark extension to parse frontmatter
Contribute
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.