Overview
Introduction
Content often starts life as HTML, a scraped web page, a CMS export, an email, but the place it needs to end up (a README, a wiki page, a static site's content folder) expects Markdown.
Doing that conversion by hand means manually rewriting every heading, link, and list item, exactly the kind of mechanical, error-prone task a real HTML parser handles more reliably.
What Is HTML to Markdown Converter?
An HTML-to-Markdown converter walks a parsed HTML tree and emits the closest Markdown equivalent for each element: headings become #, links become [text](url), and emphasis tags become * or **.
Elements with no Markdown equivalent are unwrapped rather than dropped, so their text content is preserved even when the specific tag isn't.
How HTML to Markdown Converter Works
The input is parsed and converted with `node-html-markdown`, chosen specifically because it builds its own HTML tree instead of depending on the browser's `DOMParser`, so it behaves identically whether it runs in your browser or during server-side rendering.
Everything runs client-side once your browser has loaded the page, with no upload step involved.
When To Use HTML to Markdown Converter
Use it when migrating content from a CMS export, a scraped web page, or a rich-text editor's HTML output into a Markdown-based README, wiki, or static site.
It's also useful for cleaning up HTML pasted from a word processor or email client into something readable and editable as plain text.
Often used alongside Markdown to HTML Converter, Markdown Formatter & Pretty Printer and Markdown Stripper.
Features
Advantages
- Handles nested lists, tables, and links, not just basic emphasis and paragraphs.
- Works identically regardless of rendering environment, since it doesn't depend on a browser DOM parser.
- Runs entirely client-side with no upload required.
Limitations
- Complex layout HTML (nested tables used for positioning, inline styles, embedded scripts) has no Markdown equivalent and is simplified or dropped.
- Custom HTML attributes (data-* attributes, class names) are discarded, since Markdown has no mechanism to carry them.
Examples
Best Practices & Notes
Best Practices
- Review the converted Markdown for tables and nested structures, since these are the constructs most likely to need manual touch-up.
- Strip script and style tags from the source HTML before converting if they weren't already excluded.
- Follow up with the Markdown Formatter if the converted output has inconsistent spacing you want normalized.
Developer Notes
`node-html-markdown` parses HTML with its own lightweight tree builder rather than `DOMParser`, which is why this conversion works the same during Next.js server-side rendering as it does after hydration in the browser; a `DOMParser`-based converter would throw a ReferenceError in the Node environment used for SSR, since `window`/`DOMParser` don't exist there.
HTML to Markdown Converter Use Cases
- Migrating a CMS export into a Markdown-based static site
- Converting a scraped web page's content into a README or wiki entry
- Cleaning up HTML pasted from a rich-text editor into plain Markdown
Common Mistakes
- Expecting inline styles, classes, or data attributes to survive the conversion; Markdown has no way to represent them.
- Pasting a full HTML document (with <head>/<body>) when only the content fragment was needed, pulling in unwanted boilerplate text.
Tips
- Paste just the content fragment, not the full document, to avoid converting <head> boilerplate into stray text.
- Run the result through the Markdown Formatter afterward for consistent list markers and heading spacing.