remark-rehype

remark-rehype is the plugin that lets a unified/remark pipeline hand off from the markdown world to the HTML world. Markdown processing (mdast, remark) and HTML processing (hast, rehype) are deliberately separate ecosystems in unifiedjs, because turning markdown into HTML is only one of many things people do with a markdown syntax tree (linting and formatting being two others). remark-rehype is the one plugin whose entire job is transforming an mdast tree into a hast tree via mdast-util-to-hast, after which every plugin used further down the unified().use(...) chain must be a rehype plugin rather than a remark plugin.

Beyond the core mdast-to-hast conversion, the package’s options exist almost entirely to handle the places where markdown and HTML don’t map 1-to-1: allowDangerousHtml controls whether raw HTML embedded in markdown is preserved as hast raw nodes (for later handling by rehype-raw or rehype-stringify), and a cluster of footnote* options (footnoteLabel, footnoteBackLabel, footnoteLabelProperties, clobberPrefix, etc.) control how GitHub-style footnotes are rendered accessibly and safely, since footnote IDs are derived from user content and are a known DOM-clobbering vector. Custom handlers and a passThrough list let callers override or preserve specific node types during the conversion.

It’s maintained by the remarkjs/unifiedjs core team (primarily Titus Wormer) as one of the most widely depended-upon links in the modern static site and markdown tooling chain — MDX, Astro, Next.js MDX, Docusaurus and countless documentation and blog pipelines route through it whenever they need to render markdown as HTML.

What You Get

• A unified().use(remarkRehype, options) plugin that transforms an mdast tree into a hast tree, switching the rest of the pipeline into rehype-plugin territory
• Optional bridge mode (pass a destination processor) that runs a separate rehype pipeline against the hast tree and discards its result, versus the default mutate mode that returns the hast tree directly
• Configurable, accessible footnote rendering (footnoteLabel, footnoteBackLabel, footnoteLabelProperties, clobberPrefix) that guards against DOM-clobbering via generated id attributes
• An allowDangerousHtml option to optionally preserve raw HTML found in markdown as hast raw nodes for downstream handling by rehype-raw or rehype-stringify
• Escape hatches for tree conversion: handlers to override how specific mdast node types are converted, passThrough to keep custom node types untouched, and unknownHandler for anything not otherwise recognized
• Full TypeScript types (100% type-coverage enforced in CI) for Options and all exported handler types

Common Use Cases

• Rendering markdown files to HTML in a static site generator or documentation build, piping remark-parse output through remark-rehype into rehype-stringify
• Building custom MDX-adjacent content pipelines that need rehype-side plugins (syntax highlighting via rehype-starry-night, sanitization via rehype-sanitize, HTML minification/formatting) after markdown parsing
• Rendering GitHub-flavored markdown with footnotes into accessible HTML, using the footnote-related options to produce correct ARIA-labeled backreferences
• Supporting raw HTML embedded in trusted markdown content by enabling allowDangerousHtml in combination with rehype-raw
• Feeding a bridge-mode unified() destination processor to run a full independent rehype pipeline against generated HTML without altering the outer markdown-based pipeline’s own output

Under The Hood

Architecture

remark-rehype is intentionally minimal: index.js re-exports defaultFootnoteBackContent, defaultFootnoteBackLabel, and defaultHandlers from mdast-util-to-hast alongside a default export from lib/index.js, which is the entire implementation. That single function, remarkRehype(destination, options), is a unified plugin factory with two runtime shapes chosen by inspecting whether the first argument looks like a unified Processor (has a run method): bridge mode returns an async transformer that converts the mdast tree to hast via toHast() and runs it through the given destination processor, discarding the result; mutate mode returns a synchronous transformer that converts and returns the hast tree directly so later .use() calls in the same pipeline operate on it. All the real tree-conversion logic — node type mapping, footnote handling, DOM-clobbering-safe ID generation, raw-HTML handling — lives in the separate mdast-util-to-hast dependency; remark-rehype itself is a thin, well-documented adapter around it, meaning the entire pipeline’s mdast-to-hast behavior would change if that dependency’s behavior changed.

Tech Stack

The package is pure ESM-only JavaScript ("type": "module") with zero runtime framework dependencies beyond the unified ecosystem: mdast-util-to-hast for the actual conversion, unified and vfile for the pipeline/file abstractions it operates within, and @types/hast/@types/mdast purely as type dependencies. There’s no bundler and no build step for the runtime code — tsc is used only in emitDeclarationOnly mode to generate .d.ts files from the plain JS source via extensive JSDoc type annotations, and the project targets ES2022 with Node.js 16+.