Mastering Unified: Process Markdown, HTML, and Text with AST Plugins

Overview

Unified is a text‑processing ecosystem that, together with its plugin collection, can handle Markdown, HTML, and natural‑language content. The Unified library itself acts as a unified execution interface, invoking plugins to perform specific processing tasks.

It is widely used by projects such as Prettier, the Node.js website, and Gatsby.

Plugin Ecosystem

remark

remark is a collection of plugins for Markdown parsing, transformation, and HTML generation. Common plugins include:

remark-parse : parses Markdown.

remark-gfm : adds GitHub‑flavored Markdown support.

remark-lint : provides Markdown linting.

remark-toc : generates a table of contents.

remark-html : compiles Markdown to HTML.

More than 150 remark plugins are available.

remark()
  .processSync('# Hello, world!')

The same operation using the low‑level Unified API looks like:

unified()
  .use(remarkParse)
  .use(remarkStringify)
  .processSync('# Hello, world!')

rehype

rehype is the counterpart for HTML. It offers formatting, minification, and document generation capabilities. The plugin set is smaller (around 40 plugins).

rehype can be combined with remark via rehype-remark and remark-rehype to convert between Markdown and HTML ASTs. Example converting stdin HTML to Markdown:

import { unified } from 'unified'
import { stream } from 'unified-stream'
import rehypeParse from 'rehype-parse'
import rehypeRemark from 'rehype-remark'
import remarkStringify from 'remark-stringify'

const processor = unified()
  .use(rehypeParse)      // parse HTML
  .use(rehypeRemark)    // convert to remark
  .use(remarkStringify) // stringify to Markdown

process.stdin.pipe(stream(processor)).pipe(process.stdout)

Other Plugins

retext provides natural‑language processing such as spell checking and readability analysis, while redot parses Graphviz diagrams. Additional ecosystems include mdx (Markdown with JSX) and micromark (a minimal Markdown‑to‑HTML compiler).

Working Principle

Unified operates on an abstract syntax tree (AST). When a plugin runs, it receives the AST, can read or modify it, and pass it to the next plugin. This enables language‑to‑language transformations, for example parsing Markdown to an AST, converting it to HTML, and then back to Markdown.

Example of traversing the AST to log all heading nodes:

module.exports = () => tree => {
  visit(tree, 'heading', node => {
    console.log(node)
  })
}

The visit utility comes from unist-util-visit and works across different AST formats (e.g., Markdown and HTML).

visit(markdownAST, 'images', transformImages)
visit(htmlAST, 'img', transformImgs)

Practical Scenarios

Node.js Website

Uses remark-cli for Markdown linting (see package.json scripts).

Builds documentation with Unified (see generate.mjs).

dumi

dumi is a documentation tool for component libraries that converts Markdown to HTML using Unified. Its source shows custom plugins, such as link.ts, which modify AST nodes to add external‑link icons.

[云音乐官网](https://music.163.com/ "云音乐官网")

Converted output:

<a target="_blank" rel="noopener noreferrer" href="https://music.163.com/">
  云音乐官网
  <svg class="__dumi-default-external-link-icon">…</svg>
</a>

react-markdown

react-markdown is a React component built on top of the Unified ecosystem. It parses Markdown to an AST, applies remark plugins, converts the AST to HTML AST via remark-rehype, processes it with rehype plugins, and finally renders React elements.

Convert Markdown to mdast using remark.

Apply remark plugins to mdast.

Transform mdast to hast with remark-rehype.

Apply rehype plugins to hast.

Render hast as React elements.