HAST Utility to Reparse Raw HTML Nodes

9.1.0 · active · verified Sun Apr 19

This package, `hast-util-raw`, provides a utility for re-parsing HAST (Hypertext Abstract Syntax Tree) documents, specifically targeting 'raw' nodes which contain unprocessed HTML strings. Leveraging the `parse5` HTML parser, it transforms these raw HTML strings into a proper HAST syntax tree, crucial for applications that require a fully-formed, inspectable, and transformable tree rather than mere HTML serialization. This is particularly vital when working with markdown that includes embedded HTML (often enabled via `allowDangerousHtml: true` in converters like `mdast-util-to-hast`), where the initial conversion preserves the HTML as raw strings. The utility ensures that all original data and positional information from the source HTML are meticulously retained during the reparsing process. Currently in stable version 9.1.0, the library maintains an active release cadence, frequently delivering bug fixes and minor features, with major versions introducing breaking changes, often related to Node.js version support or API enhancements. Its core differentiator lies in enabling robust processing of mixed markdown/HTML content by integrating raw HTML into the HAST ecosystem as manipulable nodes, supporting various output formats beyond simple HTML, such as React or MDX.

Common errors

```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use CommonJS `require()` syntax in an ES Module context for `hast-util-raw`.

fix Change `const { raw } = require('hast-util-raw')` to `import { raw } from 'hast-util-raw'`.
```
SVG elements (e.g., `<svg><path/></svg>`) are not closing correctly or are malformed in the output.
```
cause Parsing issues with non-lowercase SVG element tags, which could lead to incorrect HTML structure.

fix Ensure SVG element tags are consistently lowercase. This issue was specifically addressed in version 9.0.3, so upgrading may resolve it.
```
Error: parse5 could not complete parsing due to malformed HTML
```
cause The `raw` input contained unfinished or severely malformed HTML that `parse5` could not recover from.

fix Ensure that the HTML content within `raw` nodes is well-formed. This issue received a fix for certain cases in version 9.0.4, so upgrading might help, but manual correction of malformed input is often required.

Warnings

breaking Version 9.0.0 introduced a breaking change requiring Node.js 16 or higher. Earlier versions supported Node.js 14.14+ (v8.0.0) or Node.js 12 (pre-v8.0.0).
Fix: Upgrade your Node.js environment to version 16 or later.
breaking Since v9.0.0, the package is ESM-only and utilizes the `exports` field in `package.json`. Direct imports of internal/private APIs are no longer supported. The `Raw` type was also removed and should now be imported from `mdast-util-to-hast` if needed.
Fix: Ensure your project uses native ES Modules. Update import paths to use the documented public API. If you need the `Raw` type, import it from `mdast-util-to-hast`.
breaking In version 8.0.0, the `file` parameter, if previously passed directly to the `raw` function, was changed to be an option within an object: `{ file: file }`.
Fix: Update calls to `raw(tree, { file })` instead of `raw(tree, file)`.
gotcha When `allowDangerousHtml: true` is used with related utilities (like `mdast-util-to-hast`) or when `passThrough` options are configured, `hast-util-raw` can process untrusted HTML. This can lead to cross-site scripting (XSS) vulnerabilities if the input is not sanitized or trusted.
Fix: Always sanitize untrusted input before passing it to `hast-util-raw` or related utilities that enable dangerous HTML. Avoid `allowDangerousHtml: true` or `passThrough` with untrusted sources.
gotcha The `tagfilter` option, added in v9.1.0, disallows irregular tags in `raw` nodes according to GFM tagfilter rules. If you rely on specific 'irregular' tags (e.g., `iframe`, `style`, `textarea`) being processed as regular elements, this option might filter them out.
Fix: If specific tags are unexpectedly filtered, review the GFM tagfilter rules and consider setting `tagfilter: false` in the options if you explicitly need to process these tags and trust their content.

Install

npm install hast-util-raw npm
yarn add hast-util-raw yarn
pnpm add hast-util-raw pnpm

Imports

raw
wrong:
```
const raw = require('hast-util-raw')
```
correct:
```
import { raw } from 'hast-util-raw'
```
The package is ESM-only since v9.0.0. Use `import` syntax.
Options
```
import type { Options } from 'hast-util-raw'
```
Type import for configuration options such as `file`, `passThrough`, and `tagfilter`.

Quickstart

Demonstrates processing a HAST tree containing a `type: 'raw'` node with an HTML string, converting it into a fully structured HAST tree with parsed elements.

import { h } from 'hastscript';
import { raw } from 'hast-util-raw';

// A HAST tree typically containing a 'raw' node.
// In real-world scenarios, this 'treeWithRaw' often comes from a markdown-to-hast
// converter like `mdast-util-to-hast` with `allowDangerousHtml: true`.
const treeWithRaw = {
  type: 'root',
  children: [
    h('header', [h('h1', 'Document Title')]),
    // This 'raw' node contains unparsed HTML string.
    // hast-util-raw will parse this string into proper HAST elements.
    {
      type: 'raw',
      value: '<p>This is <em>some</em> <strong>raw</strong> HTML content.</p><p>Another paragraph.</p>'
    },
    h('footer', [h('p', 'End of document.')])
  ]
};

// The `raw` function processes the tree, converting 'raw' nodes to full HAST elements.
const reformattedTree = raw(treeWithRaw);

console.log(JSON.stringify(reformattedTree, null, 2));

view raw JSON →