mdast-util-frontmatter

What is mdast-util-frontmatter?

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.

What are mdast-util-frontmatter's main functionalities?

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);

Other packages similar to mdast-util-frontmatter

gray-matter

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.

remark-frontmatter

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.

front-matter

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.

README

mdast-util-frontmatter

Extension for mdast-util-from-markdown and/or mdast-util-to-markdown to support frontmatter in mdast. When parsing (from-markdown), must be combined with micromark-extension-frontmatter.

When to use this

Use this if you’re dealing with the AST manually. It’s probably nicer to use remark-frontmatter with remark, which includes this but provides a nicer interface and makes it easier to combine with hundreds of plugins.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install mdast-util-frontmatter

Use

Say we have the following file, example.md:

+++
title = "New Website"
+++

# Other markdown

And our module, example.js, looks as follows:

import fs from 'node:fs'
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 = fs.readFileSync('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 yields:

{
  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 following identifiers: frontmatterFromMarkdown, frontmatterToMarkdown. There is no default export.

frontmatterFromMarkdown([options])

frontmatterToMarkdown([options])

Support frontmatter (YAML, TOML, and more). These functions can be called with options and return extensions, respectively for mdast-util-from-markdown and mdast-util-to-markdown.

Options are the same as micromark-extension-frontmatter.

Related

• remarkjs/remark — markdown processor powered by plugins
• remarkjs/remark-frontmatter — remark plugin to support frontmatter
• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• micromark/micromark-extension-frontmatter — micromark extension to parse frontmatter
• syntax-tree/mdast-util-from-markdown — mdast parser using micromark to create mdast from markdown
• syntax-tree/mdast-util-to-markdown — mdast serializer to create markdown from mdast

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.

License

MIT © Titus Wormer