mdast-util-frontmatter
Advanced tools
mdast extension to parse and serialize frontmatter (YAML, TOML, etc)
The `mdast-util-frontmatter` package is a utility for working with frontmatter in Markdown Abstract Syntax Trees (MDAST). It allows you to parse, transform, and stringify frontmatter in Markdown documents, making it easier to handle metadata in Markdown files.
Parse Frontmatter
This feature allows you to parse frontmatter from a Markdown string into an MDAST. The example demonstrates how to parse YAML frontmatter from a Markdown document.
const { fromMarkdown } = require('mdast-util-from-markdown');
const { frontmatter } = require('mdast-util-frontmatter');
const { frontmatterFromMarkdown } = require('mdast-util-frontmatter/from-markdown');
const md = '---\ntitle: Hello World\n---\n\n# Heading\n';
const tree = fromMarkdown(md, {
extensions: [frontmatter(['yaml'])],
mdastExtensions: [frontmatterFromMarkdown(['yaml'])]
});
console.log(tree);Stringify Frontmatter
This feature allows you to stringify an MDAST with frontmatter back into a Markdown string. The example demonstrates how to convert an MDAST with YAML frontmatter into a Markdown document.
const { toMarkdown } = require('mdast-util-to-markdown');
const { frontmatter } = require('mdast-util-frontmatter');
const { frontmatterToMarkdown } = require('mdast-util-frontmatter/to-markdown');
const tree = {
type: 'root',
children: [
{
type: 'yaml',
value: 'title: Hello World'
},
{
type: 'heading',
depth: 1,
children: [{ type: 'text', value: 'Heading' }]
}
]
};
const md = toMarkdown(tree, {
extensions: [frontmatterToMarkdown(['yaml'])]
});
console.log(md);Transform Frontmatter
This feature allows you to transform frontmatter within an MDAST. The example demonstrates how to visit and modify YAML frontmatter in a Markdown document.
const { visit } = require('unist-util-visit');
const { fromMarkdown } = require('mdast-util-from-markdown');
const { frontmatter } = require('mdast-util-frontmatter');
const { frontmatterFromMarkdown } = require('mdast-util-frontmatter/from-markdown');
const md = '---\ntitle: Hello World\n---\n\n# Heading\n';
const tree = fromMarkdown(md, {
extensions: [frontmatter(['yaml'])],
mdastExtensions: [frontmatterFromMarkdown(['yaml'])]
});
visit(tree, 'yaml', node => {
node.value = 'title: Updated Title';
});
console.log(tree);The `gray-matter` package is a popular utility for parsing frontmatter from strings. It supports multiple frontmatter formats (YAML, JSON, TOML) and provides a simple API for extracting and manipulating frontmatter. Unlike `mdast-util-frontmatter`, it does not integrate directly with MDAST but is often used in conjunction with other Markdown processing tools.
The `remark-frontmatter` package is a plugin for the `remark` Markdown processor that adds support for frontmatter. It allows you to parse and stringify frontmatter in Markdown documents. While `remark-frontmatter` focuses on integrating frontmatter support into the `remark` ecosystem, `mdast-util-frontmatter` provides lower-level utilities for working directly with MDAST.
The `front-matter` package is a simple frontmatter parser that extracts metadata from strings. It supports YAML frontmatter and provides a straightforward API for parsing and manipulating frontmatter. Unlike `mdast-util-frontmatter`, it does not provide utilities for working with MDAST but is useful for basic frontmatter extraction and manipulation.
mdast extensions to parse and serialize frontmatter (YAML, TOML, and more).
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).
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 16+), install with npm:
npm install mdast-util-frontmatter
In Deno with esm.sh:
import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@2'
In browsers with esm.sh:
<script type="module">
import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@2?bundle'
</script>
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 {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):
{
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.
frontmatterFromMarkdown(options?)Create an extension for
mdast-util-from-markdown.
options (Options, optional)
— configurationExtension for mdast-util-from-markdown
(FromMarkdownExtension).
frontmatterToMarkdown(options?)Create an extension for
mdast-util-to-markdown.
options (Options, optional)
— configurationExtension for mdast-util-to-markdown
(ToMarkdownExtension).
InfoStructure of marker or fence (TypeScript type).
Same as Info from micromark-extension-frontmatter.
MatterStructure of matter (TypeScript type).
Same as Matter from micromark-extension-frontmatter.
OptionsConfiguration (TypeScript type).
Same as Options from micromark-extension-frontmatter.
See Syntax in micromark-extension-frontmatter.
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.
YAMLinterface 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
---
Yields:
{type: 'yaml', value: 'foo: bar'}
FrontmatterContenttype 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 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-markdown version 2+ and
mdast-util-to-markdown version 2+.
remark-frontmatter
— remark plugin to support frontmattermicromark-extension-frontmatter
— micromark extension to parse frontmatterSee 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.
FAQs
mdast extension to parse and serialize frontmatter (YAML, TOML, etc)
The npm package mdast-util-frontmatter receives a total of 1,002,656 weekly downloads. As such, mdast-util-frontmatter popularity was classified as popular.
We found that mdast-util-frontmatter demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.