remark-gfm vs remark-mdx vs remark-frontmatter vs remark-html vs remark-parse
Extending Markdown Processing in the Unified Ecosystem
Search packages..
remark-gfmremark-mdxremark-frontmatterremark-htmlremark-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-gfm20,684,7221,18922 kB2a year agoMIT
remark-mdx6,428,58219,44814.7 kB258 months agoMIT
remark-frontmatter032021.2 kB03 years agoMIT
remark-html033917 kB03 years agoMIT
remark-parse08,84919.5 kB83 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-gfm vs remark-mdx vs remark-frontmatter vs remark-html vs remark-parse

  • 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-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-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-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-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-gfm

remark-gfm

Build Coverage Downloads Size Sponsors Backers Chat

remark plugin to support GFM (autolink literals, footnotes, strikethrough, tables, tasklists).

Contents

What is this?

This package is a unified (remark) plugin to enable the extensions to markdown that GitHub adds with GFM: autolink literals (www.x.com), footnotes ([^1]), strikethrough (~~stuff~~), tables (| cell |…), and tasklists (* [x]). You can use this plugin to add support for parsing and serializing them. These extensions by GitHub to CommonMark are called GFM (GitHub Flavored Markdown).

This plugin does not handle how markdown is turned to HTML. That’s done by remark-rehype. If your content is not in English and uses footnotes, you should configure that plugin. When generating HTML, you might also want to enable rehype-slug to add ids on headings.

A different plugin, remark-frontmatter, adds support for frontmatter. GitHub supports YAML frontmatter for files in repos and Gists but they don’t treat it as part of GFM.

Another plugin, remark-github, adds support for how markdown works in relation to a certain GitHub repo in comments, issues, PRs, and releases, by linking references to commits, issues, and users.

Yet another plugin, remark-breaks, turns soft line endings (enters) into hard breaks (<br>s). GitHub does this in a few places (comments, issues, PRs, and releases).

When should I use this?

This project is useful when you want to support the same features that GitHub does in files in a repo, Gists, and several other places. Users frequently believe that some of these extensions, specifically autolink literals and tables, are part of normal markdown, so using remark-gfm will help match your implementation to their understanding of markdown. There are several edge cases where GitHub’s implementation works in unexpected ways or even different than described in their spec, so writing in GFM is not always the best choice.

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

Install

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

npm install remark-gfm

In Deno with esm.sh:

import remarkGfm from 'https://esm.sh/remark-gfm@4'

In browsers with esm.sh:

<script type="module">
  import remarkGfm from 'https://esm.sh/remark-gfm@4?bundle'
</script>

Use

Say our document example.md contains:

# GFM

## Autolink literals

www.example.com, https://example.com, and contact@example.com.

## Footnote

A note[^1]

[^1]: Big note.

## Strikethrough

~one~ or ~~two~~ tildes.

## Table

| a | b  |  c |  d  |
| - | :- | -: | :-: |

## Tasklist

* [ ] to do
* [x] done

…and our module example.js contains:

import rehypeStringify from 'rehype-stringify'
import remarkGfm from 'remark-gfm'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read} from 'to-vfile'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(await read('example.md'))

console.log(String(file))

…then running node example.js yields:

<h1>GFM</h1>
<h2>Autolink literals</h2>
<p><a href="http://www.example.com">www.example.com</a>, <a href="https://example.com">https://example.com</a>, and <a href="mailto:contact@example.com">contact@example.com</a>.</p>
<h2>Footnote</h2>
<p>A note<sup><a href="https://www.npmjs.com/package/remark-gfm#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>
<h2>Strikethrough</h2>
<p><del>one</del> or <del>two</del> tildes.</p>
<h2>Table</h2>
<table>
<thead>
<tr>
<th>a</th>
<th align="left">b</th>
<th align="right">c</th>
<th align="center">d</th>
</tr>
</thead>
</table>
<h2>Tasklist</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled> to do</li>
<li class="task-list-item"><input type="checkbox" checked disabled> done</li>
</ul>
<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
<ol>
<li id="user-content-fn-1">
<p>Big note. <a href="https://www.npmjs.com/package/remark-gfm#user-content-fnref-1" data-footnote-backref class="data-footnote-backref" aria-label="Back to content">↩</a></p>
</li>
</ol>
</section>

API

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

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

Add support GFM (autolink literals, footnotes, strikethrough, tables, tasklists).

Parameters
  • options (Options, optional) — configuration
Returns

Nothing (undefined).

Options

Configuration (TypeScript type).

Fields
  • firstLineBlank (boolean, default: false) — serialize with a blank line for the first line of footnote definitions
  • stringLength (((value: string) => number), default: d => d.length) — detect the size of table cells, used when aligning cells
  • singleTilde (boolean, default: true) — whether to support strikethrough with a single tilde; single tildes work on github.com, but are technically prohibited by GFM; you can always use 2 or more tildes for strikethrough
  • tablePipeAlign (boolean, default: true) — whether to align table pipes
  • tableCellPadding (boolean, default: true) — whether to add a space of padding between table pipes and cells

Examples

Example: singleTilde

To turn off support for parsing strikethrough with single tildes, pass singleTilde: false:

// …

const file = await unified()
  .use(remarkParse)
  .use(remarkGfm, {singleTilde: false})
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('~one~ and ~~two~~')

console.log(String(file))

Yields:

<p>~one~ and <del>two</del></p>

Example: stringLength

It’s possible to align tables based on the visual width of cells. First, let’s show the problem:

import {remark} from 'remark'
import remarkGfm from 'remark-gfm'

const input = `| Alpha | Bravo |
| - | - |
| 中文 | Charlie |
| 👩‍❤️‍👩 | Delta |`

const file = await remark().use(remarkGfm).process(input)

console.log(String(file))

The above code shows how remark can be used to format markdown. The output is as follows:

| Alpha    | Bravo   |
| -------- | ------- |
| 中文       | Charlie |
| 👩‍❤️‍👩 | Delta   |

To improve the alignment of these full-width characters and emoji, pass a stringLength function that calculates the visual width of cells. One such algorithm is string-width. It can be used like so:

@@ -1,5 +1,6 @@
 import {remark} from 'remark'
 import remarkGfm from 'remark-gfm'
+import stringWidth from 'string-width'

@@ -10,7 +11,7 @@ async function main() {
 | 👩‍❤️‍👩 | Delta |`

-const file = await remark().use(remarkGfm).process(input)
+const file = await remark()
+  .use(remarkGfm, {stringLength: stringWidth})
+  .process(input)

   console.log(String(file))

The output of our code with these changes is as follows:

| Alpha | Bravo   |
| ----- | ------- |
| 中文  | Charlie |
| 👩‍❤️‍👩    | Delta   |

Bugs

For bugs present in GFM but not here, or other peculiarities that are supported, see each corresponding readme:

Authoring

For recommendations on how to author GFM, see each corresponding readme:

HTML

This plugin does not handle how markdown is turned to HTML. See remark-rehype for how that happens and how to change it.

CSS

For info on how GitHub styles these features, see each corresponding readme:

Syntax

For info on the syntax of these features, see each corresponding readme:

Syntax tree

For info on the syntax tree of these features, see each corresponding readme:

Types

This package is fully typed with TypeScript. It exports the additional type Options.

The node types are supported in @types/mdast by default.

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-gfm@^4, compatible with Node.js 16.

This plugin works with remark-parse version 11+ (remark version 15+). The previous version (v3) worked with remark-parse version 10 (remark version 14). Before that, v2 worked with remark-parse version 9 (remark version 13). Earlier versions of remark-parse and remark had a gfm option that enabled this functionality, which defaulted to true.

Security

Use of remark-gfm 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.