Markdown AST to HTML AST Transformer

Common errors

• ERR_REQUIRE_ESM

  cause 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

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

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

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

Warnings

• breaking Version 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.
• breaking Node.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.
• breaking 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.
  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.
• breaking The 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.
• gotcha Double 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.

Install

• npm install mdast-util-to-hast npm
• yarn add mdast-util-to-hast yarn
• pnpm add mdast-util-to-hast pnpm

Imports

• toHast
  wrong:

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

  correct:

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

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

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

  correct:

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

  This package has no default export. All public APIs are named exports.
• Options
  wrong:

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

  correct:

  import type { 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.

Quickstart

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