{"id":11290,"library":"mdast-util-to-hast","title":"Markdown AST to HTML AST Transformer","description":"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.","status":"active","version":"13.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-util-to-hast","tags":["javascript","unist","mdast","mdast-util","hast","hast-util","util","utility","markdown","typescript"],"install":[{"cmd":"npm install mdast-util-to-hast","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-util-to-hast","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-util-to-hast","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"mdast-util-to-hast is ESM-only since v13. Use `import` statements. `require` is not supported.","wrong":"const toHast = require('mdast-util-to-hast')","symbol":"toHast","correct":"import { toHast } from 'mdast-util-to-hast'"},{"note":"This package has no default export. All public APIs are named exports.","wrong":"import toHast, { defaultFootnoteBackLabel } from 'mdast-util-to-hast'","symbol":"defaultFootnoteBackLabel","correct":"import { defaultFootnoteBackLabel } from 'mdast-util-to-hast'"},{"note":"TypeScript types should be imported using `import type` to prevent bundling issues, especially in environments that don't strip types.","wrong":"import { Options } from 'mdast-util-to-hast'","symbol":"Options","correct":"import type { Options } from 'mdast-util-to-hast'"}],"quickstart":{"code":"import { promises as fs } from 'node:fs';\nimport { toHtml } from 'hast-util-to-html';\nimport { fromMarkdown } from 'mdast-util-from-markdown';\nimport { toHast } from 'mdast-util-to-hast';\n\nasync function convertMarkdownToHtml(markdownFilePath: string): Promise<string> {\n  try {\n    const markdown = String(await fs.readFile(markdownFilePath));\n    const mdast = fromMarkdown(markdown);\n    const hast = toHast(mdast);\n    const html = toHtml(hast);\n    return html;\n  } catch (error) {\n    console.error(`Error converting markdown: ${error instanceof Error ? error.message : String(error)}`);\n    throw error;\n  }\n}\n\n// Example usage:\nconst exampleFilePath = './example.md';\nconst exampleMarkdown = `## Hello **World**!\\n\\nThis is a [link](https://example.com) and some *italic* text.\\n\\n1. Item one\\n2. Item two`;\n\nfs.writeFile(exampleFilePath, exampleMarkdown)\n  .then(() => convertMarkdownToHtml(exampleFilePath))\n  .then(html => console.log('Generated HTML:\\n', html))\n  .catch(error => console.error('Overall process failed:', error));","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 13.0.0 made the package ESM-only and removed CommonJS support. Projects must be configured to use ES modules.","severity":"breaking","affected_versions":">=13.0.0"},{"fix":"Upgrade your Node.js runtime environment to version 16 or newer. Use `nvm` or your preferred Node.js version manager.","message":"Node.js 16 or higher is now required for mdast-util-to-hast v13 and above.","severity":"breaking","affected_versions":">=13.0.0"},{"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.","message":"The behavior for footnote backreferences changed in v13.0.0 to better match GitHub's rendering. The `footnoteBackLabel` option now expects a function for i18n.","severity":"breaking","affected_versions":">=13.0.0"},{"fix":"Update your code to expect a `Node` object, potentially an empty `root` (`{ type: 'root', children: [] }`), instead of `null` or `undefined` for empty inputs.","message":"The return type of `toHast` changed in v13.0.0 to always return a node (specifically, an empty `root` node if input is empty).","severity":"breaking","affected_versions":">=13.0.0"},{"fix":"Upgrade to mdast-util-to-hast version 12.2.4 or newer to ensure correct URL encoding.","message":"Double encoding of URLs was fixed in v12.2.4. Older versions might produce incorrectly encoded URLs, leading to broken links.","severity":"gotcha","affected_versions":"<12.2.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Switch to using ES module `import` syntax and ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to use `require()` to import mdast-util-to-hast in a CommonJS environment, while the package is ESM-only.","error":"ERR_REQUIRE_ESM"},{"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\"`).","cause":"This error often occurs when mixing ESM and CJS, or when a bundler/transpiler incorrectly transforms ESM imports.","error":"TypeError: (0 , mdast_util_to_hast_1.toHast) is not a function"},{"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.","cause":"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.","error":"Error: Cannot find module 'mdast-util-to-hast' or its corresponding type declarations."},{"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.","cause":"Type incompatibility, often due to outdated `@types/mdast` or `@types/hast` packages, or passing an incorrect AST node structure.","error":"Argument of type '...' is not assignable to parameter of type 'MdastNode'."}],"ecosystem":"npm"}