patrickarlt/hast-util-to-mdast

The hast-util-to-mdast library converts HTML content into Markdown. This is handy when you have web pages or rich text formatted in HTML and need to translate it into clean, readable Markdown for documentation, a readme file, or a wiki. Under the hood, this tool takes a structural map of an HTML document and translates it into the equivalent structure for Markdown. For example, it knows that an HTML <h2> heading tag should become ## in Markdown, and that a <strong> bold tag should become **. It automatically handles paragraph spacing and tries to keep the final text as human-readable as possible. You would use this if you are building an automated tool that migrates old web content into a modern writing platform, or if you are building a system that accepts HTML pasted from a word processor but needs to save it as Markdown. The developers note that most people will actually want to use a companion tool called rehype-remark to do this job, which uses this library behind the scenes but is easier to plug into a broader content pipeline. One notable feature is that it does not just give up when it encounters HTML tags that do not exist in Markdown, like an SVG graphic. By default it drops content it cannot translate, but it gives you a way to write custom rules to pass that raw HTML straight through into the Markdown file so you do not lose your content. The developers also include a warning that if you are working with untrusted HTML, you should clean it first. If the HTML contains malicious scripts, converting it could pass that danger along into your final document.