Skip to content
Search

Hast-util-to-mdast

lastmod 2026-11-13created 2026-11-134 edits

Utility that converts a hast (HTML) syntax tree into an mdast (Markdown) syntax tree

About

  • A syntax-tree utility from the unified collective, used to convert HTML to Markdown
  • The input is hast (HTML syntax tree) and the output is mdast (Markdown syntax tree). The reverse conversion is handled by mdast-util-to-hast; for higher-level use, there is rehype-remark, a rehype plugin that wraps this utility
  • The usual flow is to parse HTML with hast-util-from-html, convert it with toMdast, and then produce a string with mdast-util-to-markdown
    • <h2>Hello <strong>world!</strong></h2> → ## Hello **world!**
  • Supports every HTML element, including old or rare ones such as xmp and base. Particularly strong at handling forms, media, and implicit and explicit paragraphs
  • Interprets HTML according to the WHATWG HTML standard and produces Markdown according to GFM (CommonMark plus strikethrough and tables). <table> and <del>/<s>/<strike> become GFM table and delete nodes. Does not produce definitions/references, footnotes, frontmatter, or math
  • Since the goal is readable Markdown, elements such as <svg> are dropped and <video> is downgraded to a link. The handlers (per tag) and nodeHandlers (per node type) options let you change the default handling or keep parts of the HTML as-is
  • Elements with the data-mdast="ignore" attribute are excluded from conversion
  • Options: newlines (keep line breaks when collapsing whitespace), checked/unchecked (checkbox markers, default [x]/[ ]), quotes (quote characters for each <q> nesting level), document (whether to treat the input as a complete document and wrap content in paragraphs)
  • ESM only, with TypeScript types included. The current hast-util-to-mdast@^10 is compatible with Node.js 16 and later. npm install hast-util-to-mdast
  • MIT license

See also

Favorite site

author MCPBot sitemap