Unified vs Remark vs Rehype: Architecting Text Transformation Pipelines

When building tools that process text—whether it's documentation, blog posts, or user comments—you often need more than simple string replacement. The unified ecosystem provides a robust way to parse text into structured data (Abstract Syntax Trees), modify that data safely, and compile it back into text. While unified, remark, and rehype are often used together, they solve distinct problems. Let's break down their roles and how they fit into a modern frontend architecture.

🏗️ The Core Engine: Unified

unified is the backbone. It doesn't know about Markdown or HTML on its own. Instead, it provides the interface to attach a parser (turns text into a tree) and a compiler (turns a tree back into text). You use unified directly when you need to bridge different formats or build a highly custom processor.

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

// Creating a custom Markdown processor using the core engine
const processor = unified()
  .use(remarkParse)      // Attach Markdown parser
  .use(remarkStringify); // Attach Markdown compiler

const file = await processor.process('# Hello World');
console.log(String(file)); // Output: '# Hello World\n'

If you only need to work with Markdown or HTML, you usually won't call unified directly. Instead, you'll use the pre-configured wrappers (remark or rehype) which already include the necessary parsers and compilers.

📝 Markdown Transformation: Remark

remark is unified pre-configured for Markdown. It parses Markdown into a mdast (Markdown AST) and compiles it back to Markdown or other formats. This is your go-to tool for authoring workflows, documentation sites, and content pipelines where the source of truth is a .md file.

Use Case: Automatically adding a Table of Contents or converting specific syntax.

import remark from 'remark';
import remarkToc from 'remark-toc';

const file = await remark()
  .use(remarkToc) // Plugin to inject Table of Contents
  .process('# My Article\n\nSome content...');

console.log(String(file)); 
// Output includes a generated [Table of Contents] section

Because remark operates on the Markdown AST, it understands the semantic structure of your document (headings, lists, code blocks) rather than just the raw characters. This makes transformations safer and more reliable than regex-based approaches.

🌐 HTML Manipulation: Rehype

rehype is unified pre-configured for HTML. It parses HTML into a hast (HTML AST) and compiles it back to HTML. Crucially, rehype runs after Markdown has been converted to HTML. This is the right place to handle browser-specific concerns, security sanitization, or injecting external resources.

Use Case: Sanitizing user input or adding target="_blank" to external links.

import rehype from 'rehype';
import rehypeExternalLinks from 'rehype-external-links';
import rehypeSanitize from 'rehype-sanitize';

const htmlString = '<p>Check <a href="https://example.com">this link</a></p>';

const file = await rehype()
  .use(rehypeSanitize)          // Remove dangerous tags/scripts
  .use(rehypeExternalLinks)     // Add target="_blank" to external links
  .process(htmlString);

console.log(String(file)); 
// Output: <p>Check <a href="https://example.com" target="_blank" rel="noopener">this link</a></p>

Since rehype works with the HTML AST, it treats your content like a DOM tree. This allows you to manipulate attributes, wrap elements, or reorder nodes with the same precision you'd have using document.querySelector in the browser, but running on the server or during a build step.

🔗 Connecting the Dots: The Full Pipeline

In real-world applications, you often need to chain these tools. A common pattern in static site generators is: Markdown (remark) → HTML (rehype) → Final Output.

You can pass the output of a remark processor directly into a rehype processor because remark can compile to HTML (using remark-rehype), and rehype expects HTML input.

import remark from 'remark';
import remarkRehype from 'remark-rehype';
import rehype from 'rehype';
import rehypeSlug from 'rehype-slug';

// 1. Parse Markdown and convert to HTML AST
// 2. Pass HTML AST to Rehype for further processing
const file = await remark()
  .use(remarkRehype) // Converts mdast -> hast
  .use(rehypeSlug)   // Adds ID attributes to headings for anchor links
  .process('# Getting Started\n\nWelcome to the guide.');

console.log(String(file)); 
// Output: <h1 id="getting-started">Getting Started</h1>...

This separation of concerns is powerful. remark handles the authoring experience (Markdown features), while rehype handles the delivery experience (HTML optimization and security).

⚖️ Key Differences at a Glance

🛠️ When to Use Which?

Choose remark when:

• Your source files are Markdown.
• You need to enforce style guides on documentation (e.g., "no dead links", "heading capitalization").
• You want to transform Markdown syntax before it becomes HTML (e.g., converting custom alerts > [!NOTE] into specific div structures).

Choose rehype when:

• You already have HTML (perhaps from a CMS or a previous build step).
• You need to sanitize content to prevent XSS attacks.
• You want to inject scripts, modify meta tags, or optimize images in the final HTML output.
• You need to manipulate the DOM structure (wrapping images in figures, adding icons to headings).

Choose unified directly when:

• You are building a plugin that needs to work with both Markdown and HTML.
• You are creating a parser for a custom format (like LaTeX or CSV) and want to leverage the plugin ecosystem.
• You need fine-grained control over the data flow between parsing and compiling stages that the pre-built presets don't offer.

💡 Architectural Best Practices

1. Keep Plugins Small: The ecosystem thrives on small, single-purpose plugins. Instead of writing one massive transformation function, chain several small plugins. This makes debugging easier and allows you to reuse logic across projects.
2. Respect the AST: Never manipulate the raw string inside a plugin unless absolutely necessary. Always traverse and modify the AST (mdast or hast). This ensures your changes don't break the structure or introduce syntax errors.
3. Order Matters: In a combined pipeline, remark plugins must run before rehype plugins. Once you convert Markdown to HTML, you lose Markdown-specific information (like the difference between *emphasis* and _emphasis_), so you can't go back.

🎯 Final Thoughts

Think of unified as the factory assembly line, remark as the station that shapes raw materials (Markdown) into components, and rehype as the station that paints and packages those components (HTML) for delivery.

For most frontend developers building content sites, you will spend 80% of your time configuring remark plugins to handle content authoring needs and 20% configuring rehype plugins to handle security and performance optimizations. Understanding where the boundary lies between Markdown processing and HTML manipulation is the key to building maintainable, scalable content pipelines.