Registry / serialization / hast-util-raw

hast-util-raw

library9.1.0jsnpmunverified

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.

serialization web-framework

npm install hast-util-raw

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-RAW

hast-util-raw

serializationjavascriptv9.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

raw

✓ import { raw } from 'hast-util-raw'

✗ const raw = require('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`.

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));

Debug

Known issues

breakingVersion 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.

affects: >=9.0.0

breakingSince 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`.

affects: >=9.0.0

breakingIn 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)`.

affects: >=8.0.0

gotchaWhen `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.

affects: >=1.0.0

gotchaThe `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.

affects: >=9.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

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.

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

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.

Upgrade

Version history

9.1.0latest on npm

Audit

Dependencies

parse5requiredCore HTML parser used to transform raw HTML strings into HAST nodes.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/hast-util-raw ↗

packagehttps://www.npmjs.com/package/hast-util-raw ↗