Registry / serialization / mdast-util-to-hast

mdast-util-to-hast

library13.2.1jsnpmunverified

mdast-util-to-hast is a foundational utility within the unified (syntax-tree) ecosystem, designed to convert an mdast (Markdown Abstract Syntax Tree) into a hast (HTML Abstract Syntax Tree). It is currently stable at version 13.2.1 and receives frequent patch and minor updates, with major versions occurring less often but bringing significant breaking changes, such as the recent v13.0.0. This package is crucial for developers building tools that process Markdown and render it to HTML, acting as the bridge between the two AST formats. Key differentiators include its tight integration with the broader unified ecosystem, offering a programmatic way to transform content, and serving as the inverse to `hast-util-to-mdast`. It is also the underlying engine for higher-level plugins like `remark-rehype`, which provides an easier abstraction for similar conversion tasks. Its focus is purely on AST transformation, providing granular control over the conversion process.

serialization data web-framework

npm install mdast-util-to-hast

github ↗package ↗

INSTALL

IMPORT

SIG · MDAST-UTIL-TO-HAST

mdast-util-to-hast

serializationjavascriptv13.2.1

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.

toHast

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

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

mdast-util-to-hast is ESM-only since v13. Use `import` statements. `require` is not supported.

defaultFootnoteBackLabel

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

✗ import toHast, { defaultFootnoteBackLabel } from 'mdast-util-to-hast'

This package has no default export. All public APIs are named exports.

Options

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

✗ import { Options } from 'mdast-util-to-hast'

TypeScript types should be imported using `import type` to prevent bundling issues, especially in environments that don't strip types.

This example demonstrates the full workflow from reading a Markdown file to converting it to an HTML string using mdast-util-to-hast and related utilities.

import { promises as fs } from 'node:fs'; import { toHtml } from 'hast-util-to-html'; import { fromMarkdown } from 'mdast-util-from-markdown'; import { toHast } from 'mdast-util-to-hast'; async function convertMarkdownToHtml(markdownFilePath: string): Promise<string> { try { const markdown = String(await fs.readFile(markdownFilePath)); const mdast = fromMarkdown(markdown); const hast = toHast(mdast); const html = toHtml(hast); return html; } catch (error) { console.error(`Error converting markdown: ${error instanceof Error ? error.message : String(error)}`); throw error; } } // Example usage: const exampleFilePath = './example.md'; const exampleMarkdown = `## Hello **World**!\n\nThis is a [link](https://example.com) and some *italic* text.\n\n1. Item one\n2. Item two`; fs.writeFile(exampleFilePath, exampleMarkdown) .then(() => convertMarkdownToHtml(exampleFilePath)) .then(html => console.log('Generated HTML:\n', html)) .catch(error => console.error('Overall process failed:', error));

Debug

Known issues

breakingVersion 13.0.0 made the package ESM-only and removed CommonJS support. Projects must be configured to use ES modules.

fix

Migrate your project to use ES Modules, update your `package.json` with `"type": "module"` or use `.mjs` files, and update `require()` calls to `import` statements.

affects: >=13.0.0

breakingNode.js 16 or higher is now required for mdast-util-to-hast v13 and above.

fix

Upgrade your Node.js runtime environment to version 16 or newer. Use `nvm` or your preferred Node.js version manager.

affects: >=13.0.0

breakingThe behavior for footnote backreferences changed in v13.0.0 to better match GitHub's rendering. The `footnoteBackLabel` option now expects a function for i18n.

fix

If customizing footnote back labels, ensure you are passing a function to the `footnoteBackLabel` option, taking `referenceIndex` and `rereferenceIndex` as arguments. Consult `defaultFootnoteBackLabel` for an example.

affects: >=13.0.0

breakingThe return type of `toHast` changed in v13.0.0 to always return a node (specifically, an empty `root` node if input is empty).

fix

Update your code to expect a `Node` object, potentially an empty `root` (`{ type: 'root', children: [] }`), instead of `null` or `undefined` for empty inputs.

affects: >=13.0.0

gotchaDouble encoding of URLs was fixed in v12.2.4. Older versions might produce incorrectly encoded URLs, leading to broken links.

fix

Upgrade to mdast-util-to-hast version 12.2.4 or newer to ensure correct URL encoding.

affects: <12.2.4

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to use `require()` to import mdast-util-to-hast in a CommonJS environment, while the package is ESM-only.

fix

Switch to using ES module `import` syntax and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

TypeError: (0 , mdast_util_to_hast_1.toHast) is not a function

This error often occurs when mixing ESM and CJS, or when a bundler/transpiler incorrectly transforms ESM imports.

fix

Ensure consistent ESM usage throughout your project. If using TypeScript, check `tsconfig.json` for `module` and `moduleResolution` settings (e.g., `"module": "node16", "moduleResolution": "node16"`).

Error: Cannot find module 'mdast-util-to-hast' or its corresponding type declarations.

The package is not installed, or Node.js module resolution is failing to locate it, possibly due to a misconfigured `exports` map or incorrect import path in older Node.js versions.

fix

Run `npm install mdast-util-to-hast`. Ensure Node.js 16+ is used if on v13+ of the library, and that your `tsconfig.json` (if applicable) aligns with ESM resolution.

Argument of type '...' is not assignable to parameter of type 'MdastNode'.

Type incompatibility, often due to outdated `@types/mdast` or `@types/hast` packages, or passing an incorrect AST node structure.

fix

Update `@types/mdast` and `@types/hast` to match the major version used by `mdast-util-to-hast` (v13 requires compatible types). Ensure the input `tree` adheres to the `MdastNode` interface.

Upgrade

Version history

13.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

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

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