Registry / serialization / hast-util-to-mdast

hast-util-to-mdast

library10.1.2jsnpmunverified

hast-util-to-mdast is a core utility within the unified.js ecosystem designed to transform a HAST (HTML Abstract Syntax Tree) into an MDAST (Markdown Abstract Syntax Tree). This package is essential for converting HTML content into Markdown programmatically, often serving as the engine behind higher-level plugins like `rehype-remark`. The current stable version is 10.1.2. The package maintains an active release cadence, with frequent patch and minor updates addressing bug fixes and feature enhancements, alongside major versions that typically align with Node.js LTS updates or significant API refinements. Key differentiators include its tight integration with the unified ecosystem, robust handling of various HTML structures, and the provision of a flexible API with custom handlers for fine-grained control over the transformation process, allowing developers to define how specific HTML elements or nodes should be represented in Markdown.

serialization data

npm install hast-util-to-mdast

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-TO-MDAST

hast-util-to-mdast

serializationjavascriptv10.1.2

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.

toMdast

✓ import { toMdast } from 'hast-util-to-mdast'

✗ const toMdast = require('hast-util-to-mdast')

This package is ESM-only since v10.0.0. CommonJS `require` will not work.

defaultHandlers

✓ import { defaultHandlers } from 'hast-util-to-mdast'

Provides the default handling logic for HTML elements, useful for extending or overriding behavior with custom handlers.

State

✓ import type { State } from 'hast-util-to-mdast'

TypeScript type for the state object passed to handlers, essential when implementing custom transformation logic. Import with `type` keyword.

Demonstrates how to convert an HTML string to Markdown using `hast-util-from-html`, `hast-util-to-mdast`, and `mdast-util-to-markdown`.

import fs from 'node:fs/promises'; import { fromHtml } from 'hast-util-from-html'; import { toMdast } from 'hast-util-to-mdast'; import { toMarkdown } from 'mdast-util-to-markdown'; async function convertHtmlToMarkdown(htmlString: string): Promise<string> { // Parse the HTML string into a HAST (HTML Abstract Syntax Tree) fragment. const hast = fromHtml(htmlString, { fragment: true }); // Transform the HAST tree into an MDAST (Markdown Abstract Syntax Tree). const mdast = toMdast(hast); // Serialize the MDAST tree back into a Markdown string. const markdown = toMarkdown(mdast); return markdown; } // Example usage: const exampleHtml = '<h2>Hello <strong>world!</strong></h2><p>This is a paragraph with a <a href="#">link</a> and a <br>line break.</p>'; convertHtmlToMarkdown(exampleHtml) .then(markdown => { console.log('Original HTML:\n', exampleHtml); console.log('\nConverted Markdown:\n', markdown); }) .catch(error => { console.error('Conversion failed:', error); }); // To show an actual file read (requires 'example.html' file): // const htmlFilePath = './example.html'; // try { // const fileHtml = await fs.readFile(htmlFilePath, 'utf8'); // const convertedFileMarkdown = await convertHtmlToMarkdown(fileHtml); // console.log(`\nMarkdown from ${htmlFilePath}:\n`, convertedFileMarkdown); // } catch (err) { // console.error(`Could not read file ${htmlFilePath}:`, err); // }

Debug

Known issues

breakingVersion 10.0.0 introduced a breaking change requiring Node.js 16 or later. Previous versions (9.x) supported Node.js 14.14+ or later, and earlier versions supported Node.js 12+.

fix

Ensure your project uses Node.js v16.0.0 or higher. Update your Node.js runtime if necessary.

affects: >=10.0.0

breakingSince version 10.0.0, this package is ESM-only (ECMAScript Modules). The 'exports' field was added to `package.json`, making CommonJS `require()` incompatible.

fix

Refactor your imports to use ESM syntax (e.g., `import { toMdast } from 'hast-util-to-mdast'`). If your project is still CommonJS, consider transpilation or upgrading your project to use ESM.

affects: >=10.0.0

breakingVersion 9.0.0 significantly changed the API for custom handlers. The `h` parameter was replaced with a more powerful `state` object, and the `one` and `all` exports were removed in favor of `state.one` and `state.all`.

fix

If you are using custom handlers, consult the official documentation for the new API. You will need to rewrite your handler functions to use the `state` object and its methods (e.g., `state.one`, `state.all`).

affects: >=9.0.0 <10.0.0

gotchaPrior to version 10.1.2, `br` (line break) elements within phrasing content could be unexpectedly dropped during the transformation process, leading to a loss of intended layout.

fix

Update to `hast-util-to-mdast@10.1.2` or later to ensure `br` elements are correctly preserved in phrasing content.

affects: <10.1.2

Errors

Common errors & fixes

TypeError: require is not a function in ES module scope

Attempting to use `require()` to import `hast-util-to-mdast` in a project configured for ESM, or after upgrading to v10+ in a CommonJS project.

fix

Change `const { toMdast } = require('hast-util-to-mdast');` to `import { toMdast } from 'hast-util-to-mdast';`. Ensure your project's `package.json` includes `"type": "module"` or uses `.mjs` files for ESM.

TypeError: Cannot read properties of undefined (reading 'one') or (reading 'all')

You've upgraded from a version prior to 9.0.0 to 9.0.0 or later and are still trying to import or use `one` or `all` functions directly.

fix

These functions are no longer direct exports. When implementing custom handlers, access them via the `state` object passed to your handler: `state.one(node, parent)` and `state.all(node, parent)`.

Error: This package now requires Node.js 16. Please upgrade your Node.js version.

Running `hast-util-to-mdast` version 10.0.0 or higher on an unsupported Node.js version (e.g., Node.js 14).

fix

Upgrade your Node.js runtime environment to version 16 or newer. Use `nvm install 16` (or higher) and `nvm use 16` if using Node Version Manager.

Upgrade

Version history

10.1.2latest on npm

Audit

Dependencies

hastrequiredCore AST specification for HTML, used as input tree type.

mdastrequiredCore AST specification for Markdown, used as output tree type.

hast-util-from-htmloptionalCommonly used to parse HTML strings into a HAST tree before passing to hast-util-to-mdast.

mdast-util-to-markdownoptionalCommonly used to serialize the resulting MDAST tree back into a Markdown string.

rehype-remarkoptionalA rehype plugin that wraps this utility, providing a higher-level abstraction for HTML-to-Markdown conversion within a unified pipeline.

Agent activity

8 hits · last 30 days

node

Resources

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

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