remark-frontmatter vs remark-gfm vs remark-html vs remark-mdx vs remark-parse
Extending Markdown Processing in the Unified Ecosystem
Search packages..
remark-frontmatterremark-gfmremark-htmlremark-mdxremark-parseSimilar Packages:

Extending Markdown Processing in the Unified Ecosystem

remark-frontmatter, remark-gfm, remark-html, remark-mdx, and remark-parse are plugins or core components in the Unified ecosystem (specifically Remark) that enable advanced Markdown processing. remark-parse is the foundational parser that converts Markdown strings into an abstract syntax tree (AST). The other packages are plugins that extend this AST: remark-frontmatter handles YAML/TOML frontmatter, remark-gfm adds GitHub Flavored Markdown support (tables, task lists, etc.), remark-html transforms the AST into HTML strings, and remark-mdx enables parsing and processing of MDX (Markdown + JSX). Together, they allow developers to build customizable, powerful Markdown-to-HTML pipelines with support for metadata, extended syntax, and embedded components.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
remark-frontmatter032021.2 kB03 years agoMIT
remark-gfm01,21222 kB2a year agoMIT
remark-html033817 kB03 years agoMIT
remark-mdx019,56414.7 kB229 months agoMIT
remark-parse08,89619.5 kB93 years agoMIT

Processing Markdown with Remark: Parsing, Extending, and Serializing

When building modern content pipelines — whether for blogs, documentation, or CMS backends — developers often reach for the Unified ecosystem, where Remark handles Markdown processing. The packages remark-parse, remark-frontmatter, remark-gfm, remark-mdx, and remark-html each play distinct roles in this pipeline. Understanding how they fit together — and when to use which — is key to building efficient, maintainable systems.

🧱 Core Roles: Parser, Transformers, and Serializer

Every Remark pipeline follows a simple flow:

  1. Parse Markdown text into an AST (remark-parse)
  2. Transform the AST with plugins (e.g., remark-gfm, remark-frontmatter, remark-mdx)
  3. Serialize the AST into output (e.g., remark-html for HTML strings)

Let’s see how each package fits into this flow.

remark-parse: The Foundation

This is the only parser in the list. Without it, you can’t process Markdown at all in a Remark pipeline. It converts a string like # Hello into a structured tree that other tools can modify.

import { unified } from 'unified';
import remarkParse from 'remark-parse';

const processor = unified().use(remarkParse);
const ast = processor.parse('# Hello');
// Returns a root node with a heading child

⚠️ You must use remark-parse (or a compatible parser) before applying any Remark plugins. None of the other packages in this comparison can parse raw Markdown on their own.

remark-html: The Output Generator

Once you have an AST, remark-html turns it into a plain HTML string. It’s a compiler, not a transformer — it doesn’t modify the AST; it consumes it.

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkHtml from 'remark-html';

const processor = unified()
  .use(remarkParse)
  .use(remarkHtml);

const html = processor.processSync('# Hello').toString();
// Returns '<h1>Hello</h1>'

Note: remark-html works after all transformations. If you’ve added GFM tables or MDX components, remark-html won’t know how to render them unless you’ve first converted those nodes to standard HTML-compatible ones (usually via remark-rehype). But for basic Markdown, it’s sufficient.

remark-frontmatter, remark-gfm, remark-mdx: AST Transformers

These three modify the AST during processing. They must come after remark-parse and before serialization.

remark-frontmatter: Extracting Metadata

Handles frontmatter blocks like:

---
title: My Post
date: 2024-01-01
---

# Content

Usage:

import remarkFrontmatter from 'remark-frontmatter';

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter, ['yaml', 'toml']); // supports multiple formats

const ast = processor.parse('---\ntitle: Test\n---\n# Hi');
// AST now includes a `yaml` node at the top

Without this plugin, the --- block would be parsed as a thematic break (horizontal rule), corrupting your metadata.

remark-gfm: Adding GitHub Flavored Markdown

Enables syntax like tables, task lists, and autolinks:

| Name | Age |
|------|-----|
| Alice| 30  |

- [x] Done
- [ ] Todo

Visit https://example.com

Usage:

import remarkGfm from 'remark-gfm';

const processor = unified()
  .use(remarkParse)
  .use(remarkGfm);

const ast = processor.parse('| A | B |\n|---|---|\n| 1 | 2 |');
// AST includes a `table` node

Without remark-gfm, that table would be parsed as plain paragraphs.

remark-mdx: Embedding JSX in Markdown

Allows mixing React-like components in Markdown:

# Hello

Here is a chart:

<BarChart data={data} />

Usage:

import remarkMdx from 'remark-mdx';

const processor = unified()
  .use(remarkParse)
  .use(remarkMdx);

const ast = processor.parse('# Hi\n\n<MyComponent />');
// AST includes an `mdxJsxTextElement` node

🔒 Warning: MDX execution can introduce security risks (e.g., arbitrary code injection) if used with untrusted input. Always sanitize or restrict component usage in public-facing apps.

🔄 Pipeline Order Matters

The sequence of plugins affects correctness. Here’s a typical full pipeline for GFM + frontmatter:

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkFrontmatter from 'remark-frontmatter';
import remarkGfm from 'remark-gfm';
import remarkHtml from 'remark-html';

const processor = unified()
  .use(remarkParse)
  .use(remarkFrontmatter, ['yaml'])
  .use(remarkGfm)
  .use(remarkHtml);

const result = processor.processSync(`---
title: Demo
---

- [x] Task

| A | B |
|---|---|`);

If you put remark-html before remark-gfm, tables won’t render — because the HTML compiler runs before the GFM syntax is recognized.

🛑 What These Packages Don’t Do

  • None of them handle HTML sanitization — if you output HTML from user content, use rehype-sanitize.
  • remark-mdx does not execute JSX — it only parses it into an AST. To render components, you need additional tooling (e.g., @mdx-js/react).
  • remark-html cannot render MDX components — it outputs literal <MyComponent /> as a string. For component-aware rendering, convert to React via remark-rehype + rehype-react.

🧩 When to Combine vs. Use Alone

Use CaseRequired Packages
Basic Markdown → HTMLremark-parse + remark-html
Markdown with YAML metadataAdd remark-frontmatter
GitHub-style MarkdownAdd remark-gfm
Interactive docs with componentsReplace remark-html with MDX-aware pipeline (remark-mdx → remark-rehype → rehype-react)

💡 Practical Recommendation

Start minimal: always begin with remark-parse and remark-html. Then layer in transformers only as needed:

  • Need metadata? → add remark-frontmatter
  • Accepting GitHub-style input? → add remark-gfm
  • Building a React-based docs site? → replace remark-html with an MDX pipeline using remark-mdx

Avoid over-engineering. If you don’t use tables or task lists, skip remark-gfm. If you don’t have frontmatter, skip remark-frontmatter. Each plugin adds maintenance surface and potential edge cases.

By understanding these roles — parser, transformers, serializer — you’ll build cleaner, more predictable Markdown processing systems.

How to Choose: remark-frontmatter vs remark-gfm vs remark-html vs remark-mdx vs remark-parse

  • remark-frontmatter:

    Choose remark-frontmatter when your Markdown files include metadata blocks (like YAML or TOML) at the top — common in static site generators like Jekyll or Hugo. It safely extracts this data into the AST without affecting the rest of the document. Avoid it if your content doesn’t use frontmatter, as it adds unnecessary parsing overhead.

  • remark-gfm:

    Choose remark-gfm when you need to support GitHub-style Markdown features such as tables, strikethrough, task lists, or autolinks. This is essential for user-generated content from GitHub or tools that expect GFM compatibility. Don’t use it if you only need standard CommonMark compliance, as it introduces extra syntax rules that may not be needed.

  • remark-html:

    Choose remark-html when your goal is to convert a Markdown AST into a plain HTML string for rendering in browsers or email templates. It’s the standard serializer after parsing and transforming Markdown. Avoid using it if you’re targeting React (use rehype-react instead) or another output format like JSON or PDF.

  • remark-mdx:

    Choose remark-mdx when you need to process MDX — Markdown that supports embedded JSX components. This is critical for documentation sites, interactive blogs, or design systems built with frameworks like Next.js or Gatsby. Only use it if you actually require component interpolation; otherwise, stick with standard Markdown plugins to avoid complexity and security considerations.

  • remark-parse:

    Choose remark-parse whenever you start processing Markdown in a Unified pipeline — it’s the required first step to turn raw Markdown text into a syntax tree that other plugins can transform. Never skip it unless you’re working directly with an existing AST. It’s lightweight and focused solely on parsing, so always include it in any Remark-based workflow.

Similar Npm Packages to remark-frontmatter

remark-frontmatter is a plugin for the Remark library that allows you to parse frontmatter from Markdown files. Frontmatter is a way to include metadata at the top of a Markdown document, typically in YAML format. This metadata can be used for various purposes, such as defining the title, date, tags, and other attributes of the content. By using remark-frontmatter, developers can easily extract and utilize this metadata when processing Markdown files, making it a valuable tool for static site generators and content management systems.

While remark-frontmatter serves a specific purpose, there are several alternatives within the Remark ecosystem that cater to different needs:

  • remark-gfm is a plugin that adds support for GitHub Flavored Markdown (GFM) to Remark. It extends the standard Markdown syntax to include features like task lists, strikethroughs, and tables, which are commonly used in GitHub repositories. If you need to work with Markdown that includes these additional features, remark-gfm is an excellent choice.
  • remark-html is a plugin that converts Markdown content into HTML. This is particularly useful when you want to render Markdown in a web application or convert it for use in a static site. By using remark-html, developers can easily transform their Markdown documents into HTML format while preserving the structure and semantics of the original content.
  • remark-mdx is a plugin that enables the use of MDX, which allows you to write JSX within Markdown files. This is particularly useful for documentation and blog posts that require interactive components or custom React components. If your project involves using React components alongside Markdown content, remark-mdx provides a seamless way to integrate the two.
  • remark-parse is the core parser for Remark that converts Markdown text into a syntax tree. It is the foundational plugin that allows other Remark plugins to operate on the parsed Markdown content. If you are building a custom Markdown processing pipeline, remark-parse is essential for converting raw Markdown into a format that can be manipulated by other plugins.

To explore how remark-frontmatter compares with these alternatives, check out the comparison: Comparing remark-frontmatter vs remark-gfm vs remark-html vs remark-mdx vs remark-parse.

Similar Npm Packages to remark-parse

remark-parse is a Markdown parser that is part of the unified ecosystem, designed to convert Markdown content into a syntax tree that can be manipulated or transformed. It is particularly useful for developers who want to work with Markdown in a structured way, allowing for further processing or transformations using other unified plugins. While remark-parse is a powerful tool for parsing Markdown, there are several alternatives available in the ecosystem. Here are a few notable ones:

  • markdown-it is a fast and flexible Markdown parser that offers a rich set of features and plugins. It is designed to be extensible, allowing developers to customize the parsing process and add additional functionality as needed. If you are looking for a highly customizable Markdown parser with a focus on performance, markdown-it is an excellent choice. Its plugin ecosystem also enables you to enhance its capabilities easily.
  • marked is another popular Markdown parser that is known for its speed and simplicity. It is designed to be lightweight and efficient, making it suitable for applications that require quick parsing of Markdown content. marked supports a variety of Markdown features and is easy to integrate into existing projects. If you need a straightforward and fast solution for parsing Markdown, marked is a great option.
  • remark is a Markdown processor built on the unified framework, which allows for parsing, transforming, and serializing Markdown. It provides a comprehensive set of tools for working with Markdown content, including plugins for linting, formatting, and transforming Markdown. If you are looking for a complete solution that allows you to not only parse but also manipulate and transform Markdown, remark is an ideal choice.
  • unified is a framework for processing content with syntax trees, and it serves as the foundation for remark and other processors. While unified itself is not a Markdown parser, it provides the tools and architecture needed to build custom processors for various content types, including Markdown. If you are looking to create a highly customized content processing pipeline, leveraging unified along with remark-parse can be a powerful approach.

For a detailed comparison of these packages, check out: Comparing markdown-it vs marked vs remark vs remark-parse vs unified.

README for remark-frontmatter

remark-frontmatter

Build Coverage Downloads Size Sponsors Backers Chat

remark plugin to support frontmatter (YAML, TOML, and more).

Contents

What is this?

This package is a unified (remark) plugin to add support for YAML, TOML, and other frontmatter.

Frontmatter is a metadata format in front of the content. It’s typically written in YAML and is often used with markdown.

This plugin follow how GitHub handles frontmatter. GitHub only supports YAML frontmatter, but this plugin also supports different flavors (such as TOML).

When should I use this?

You can use frontmatter when you want authors, that have some markup experience, to configure where or how the content is displayed or supply metadata about content, and know that the markdown is only used in places that support frontmatter. A good example use case is markdown being rendered by (static) site generators.

If you just want to turn markdown into HTML (with maybe a few extensions such as frontmatter), we recommend micromark with micromark-extension-frontmatter instead. If you don’t use plugins and want to access the syntax tree, you can use mdast-util-from-markdown with mdast-util-frontmatter.

Install

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

npm install remark-frontmatter

In Deno with esm.sh:

import remarkFrontmatter from 'https://esm.sh/remark-frontmatter@5'

In browsers with esm.sh:

<script type="module">
  import remarkFrontmatter from 'https://esm.sh/remark-frontmatter@5?bundle'
</script>

Use

Say our document example.md contains:

+++
layout = "solar-system"
+++

# Jupiter

…and our module example.js contains:

import remarkFrontmatter from 'remark-frontmatter'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
import {read} from 'to-vfile'

const file = await unified()
  .use(remarkParse)
  .use(remarkStringify)
  .use(remarkFrontmatter, ['yaml', 'toml'])
  .use(function () {
    return function (tree) {
      console.dir(tree)
    }
  })
  .process(await read('example.md'))

console.log(String(file))

…then running node example.js yields:

{
  type: 'root',
  children: [
    {type: 'toml', value: 'layout = "solar-system"', position: [Object]},
    {type: 'heading', depth: 1, children: [Array], position: [Object]}
  ],
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 6, column: 1, offset: 43}
  }
}

+++
layout = "solar-system"
+++

# Jupiter

API

This package exports no identifiers. The default export is remarkFrontmatter.

unified().use(remarkFrontmatter[, options])

Add support for frontmatter.

Parameters
  • options (Options, default: 'yaml') — configuration
Returns

Nothing (undefined).

Notes

Doesn’t parse the data inside them: create your own plugin to do that.

Options

Configuration (TypeScript type).

Type
type Options = Array<Matter | Preset> | Matter | Preset

/**
 * Sequence.
 *
 * Depending on how this structure is used, it reflects a marker or a fence.
 */
export type Info = {
  /**
   * Closing.
   */
  close: string
  /**
   * Opening.
   */
  open: string
}

/**
 * Fence configuration.
 */
type FenceProps = {
  /**
   * Complete fences.
   *
   * This can be used when fences contain different characters or lengths
   * other than 3.
   * Pass `open` and `close` to interface to specify different characters for opening and
   * closing fences.
   */
  fence: Info | string
  /**
   * If `fence` is set, `marker` must not be set.
   */
  marker?: never
}

/**
 * Marker configuration.
 */
type MarkerProps = {
  /**
   * Character repeated 3 times, used as complete fences.
   *
   * For example the character `'-'` will result in `'---'` being used as the
   * fence
   * Pass `open` and `close` to specify different characters for opening and
   * closing fences.
   */
  marker: Info | string
  /**
   * If `marker` is set, `fence` must not be set.
   */
  fence?: never
}

/**
 * Fields describing a kind of matter.
 *
 * > 👉 **Note**: using `anywhere` is a terrible idea.
 * > It’s called frontmatter, not matter-in-the-middle or so.
 * > This makes your markdown less portable.
 *
 * > 👉 **Note**: `marker` and `fence` are mutually exclusive.
 * > If `marker` is set, `fence` must not be set, and vice versa.
 */
type Matter = (MatterProps & FenceProps) | (MatterProps & MarkerProps)

/**
 * Fields describing a kind of matter.
 */
type MatterProps = {
  /**
   * Node type to tokenize as.
   */
  type: string
  /**
   * Whether matter can be found anywhere in the document, normally, only matter
   * at the start of the document is recognized.
   *
   * > 👉 **Note**: using this is a terrible idea.
   * > It’s called frontmatter, not matter-in-the-middle or so.
   * > This makes your markdown less portable.
   */
  anywhere?: boolean | null | undefined
}

/**
 * Known name of a frontmatter style.
 */
type Preset = 'toml' | 'yaml'

Examples

Example: different markers and fences

Here are a couple of example of different matter objects and what frontmatter they match.

To match frontmatter with the same opening and closing fence, namely three of the same markers, use for example {type: 'yaml', marker: '-'}, which matches:

---
key: value
---

To match frontmatter with different opening and closing fences, which each use three different markers, use for example {type: 'custom', marker: {open: '<', close: '>'}}, which matches:

<<<
data
>>>

To match frontmatter with the same opening and closing fences, which both use the same custom string, use for example {type: 'custom', fence: '+=+=+=+'}, which matches:

+=+=+=+
data
+=+=+=+

To match frontmatter with different opening and closing fences, which each use different custom strings, use for example {type: 'json', fence: {open: '{', close: '}'}}, which matches:

{
  "key": "value"
}

Example: frontmatter as metadata

This plugin handles the syntax of frontmatter in markdown. It does not parse that frontmatter as say YAML or TOML and expose it somewhere.

In unified, there is a place for metadata about files: file.data. For frontmatter specifically, it’s customary to expose parsed data at file.data.matter.

We can make a plugin that does this. This example uses the utility vfile-matter, which is specific to YAML. To support other data languages, look at this utility for inspiration.

my-unified-plugin-handling-yaml-matter.js:

/**
 * @typedef {import('unist').Node} Node
 * @typedef {import('vfile').VFile} VFile
 */

import {matter} from 'vfile-matter'

/**
 * Parse YAML frontmatter and expose it at `file.data.matter`.
 *
 * @returns
 *   Transform.
 */
export default function myUnifiedPluginHandlingYamlMatter() {
  /**
   * Transform.
   *
   * @param {Node} tree
   *   Tree.
   * @param {VFile} file
   *   File.
   * @returns {undefined}
   *   Nothing.
   */
  return function (tree, file) {
    matter(file)
  }
}

…with an example markdown file example.md:

---
key: value
---

# Venus

…and using the plugin with an example.js containing:

import remarkParse from 'remark-parse'
import remarkFrontmatter from 'remark-frontmatter'
import remarkStringify from 'remark-stringify'
import {read} from 'to-vfile'
import {unified} from 'unified'
import myUnifiedPluginHandlingYamlMatter from './my-unified-plugin-handling-yaml-matter.js'

const file = await unified()
  .use(remarkParse)
  .use(remarkStringify)
  .use(remarkFrontmatter)
  .use(myUnifiedPluginHandlingYamlMatter)
  .process(await read('example.md'))

console.log(file.data.matter) // => {key: 'value'}

Example: frontmatter in MDX

MDX has the ability to export data from it, where markdown does not. When authoring MDX, you can write export statements and expose arbitrary data through them. It is also possible to write frontmatter, and let a plugin turn those into export statements.

To automatically turn frontmatter into export statements, use remark-mdx-frontmatter.

With an example.mdx as follows:

---
key: value
---

# Mars

This plugin can be used as follows:

import {compile} from '@mdx-js/mdx'
import remarkFrontmatter from 'remark-frontmatter'
import remarkMdxFrontmatter from 'remark-mdx-frontmatter'
import {read, write} from 'to-vfile'

const file = await compile(await read('example.mdx'), {
  remarkPlugins: [remarkFrontmatter, [remarkMdxFrontmatter, {name: 'matter'}]]
})
file.path = 'output.js'
await write(file)

const mod = await import('./output.js')
console.log(mod.matter) // => {key: 'value'}

Authoring

When authoring markdown with frontmatter, it’s recommended to use YAML frontmatter if possible. While YAML has some warts, it works in the most places, so using it guarantees the highest chance of portability.

In certain ecosystems, other flavors are widely used. For example, in the Rust ecosystem, TOML is often used. In such cases, using TOML is an okay choice.

When possible, do not use other types of frontmatter, and do not allow frontmatter anywhere.

HTML

Frontmatter does not relate to HTML elements. It is typically stripped, which is what remark-rehype does.

CSS

This package does not relate to CSS.

Syntax

See Syntax in micromark-extension-frontmatter.

Syntax tree

See Syntax tree in mdast-util-frontmatter.

Types

This package is fully typed with TypeScript. It exports the additional type 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 {Data, Literal} from 'mdast'

interface Toml extends Literal {
  type: 'toml'
  data?: TomlData
}

declare module 'mdast' {
  interface FrontmatterContentMap {
    // Allow using TOML nodes defined by `remark-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, remark-frontmatter@^5, compatible with Node.js 16.

This plugin works with unified 6+ and remark 13+.

Security

Use of remark-frontmatter does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS) attacks.

Related

Contribute

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

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. Please share your feedback via our GitHub repository. For more details, please refer to our Terms & Privacy.