rehype-raw

rehype-raw is a unified/rehype plugin that takes a hast (HTML AST) tree containing strings of raw HTML and reparses it through the parse5 HTML parser, recreating the tree exactly as a browser would while preserving the original data and positional information. It is the standard bridge for pipelines that come from markdown with embedded HTML: after remark-rehype passes HTML through as opaque raw nodes, rehype-raw turns those strings into actual element nodes so downstream plugins, and output formats like React or MDX, can operate on a proper tree instead of unparseable HTML strings.

What You Get

• A single default-export rehype plugin you drop into a unified().use(...) chain
• Accurate reparsing of embedded raw HTML into hast element nodes via the parse5 browser-grade parser
• Preserved positional information (line/column data) across the reparse
• An optional GFM tagfilter mode to neutralize dangerous tags like script, iframe, and style
• A passThrough option to keep specified custom node types untouched during reparsing
• Full TypeScript types (ESM-only, ships an Options type)

Common Use Cases

• Rendering markdown that contains inline HTML to React or MDX components
• Running rehype transform plugins over content that mixed in raw HTML blocks
• Producing a clean HTML AST from remark-rehype output generated with allowDangerousHtml: true
• Applying GFM tagfilter rules to block irregular or unsafe tags in user-authored HTML

Under The Hood

Architecture

The package is intentionally thin. The public entry index.js re-exports the default from lib/index.js, which defines a single rehypeRaw(options) factory. That factory returns a unified transformer (tree, file) that delegates all real work to raw() from hast-util-raw, spreading the caller’s options and injecting the current file so positional/message context is preserved. hast-util-raw in turn runs the tree through parse5, so the tree is reconstructed exactly as a browser HTML parser would build it. The plugin itself owns no parsing logic — it is a well-scoped adapter that wires rehype’s plugin contract onto the underlying hast utility.

Tech Stack

Written in modern ESM JavaScript targeting Node.js 16+, with types authored as JSDoc and emitted to .d.ts via the TypeScript compiler (tsc --build). Runtime dependencies are minimal and current: hast-util-raw ^9, @types/hast ^3, and vfile ^6. Tooling includes xo + prettier for lint/format, remark-cli with remark-preset-wooorm for docs, c8 for coverage, and type-coverage enforcing 100% typed code. There is no bundler — the package ships source ESM directly.

Code Quality

Code quality is high for a micro-package. type-coverage is pinned at 100% with strict TypeScript checking of JS, and the tsconfig enables strict and exactOptionalPropertyTypes. test.js uses the built-in node:test runner with node:assert/strict and covers the public API surface, the core markdown-with-embedded-HTML reparse case, and the tagfilter behavior; the CI test script requires 100% coverage via c8 --100. Naming and structure are clear, and the single transformer is small enough to reason about completely.

API Design

The API is minimal and idiomatic to unified: a default export you .use() with an optional options object (passThrough, tagfilter). There are no other identifiers to learn, options mirror the underlying hast-util-raw configuration, and the README’s runnable end-to-end example gets a new user productive quickly. The main friction is conceptual rather than ergonomic — using it well requires understanding the hast AST and where reparsing fits in a remark/rehype pipeline.