Web & APIs · 4 min read
Converting HTML to Markdown: What Survives and What Does Not
Moving a blog to a static site generator, pasting a web page into documentation, or feeding a page to an AI tool — all of these go smoother in Markdown. Converting from HTML is mostly straightforward, but Markdown is a smaller language, so some things cannot make the trip.
Try it yourself with the related tool.
Convert HTML to Markdown →Advertisement
What maps cleanly
Headings become # lines, <strong> and <em> become **bold** and *italic*, links become [text](url), images become , lists keep their structure, <code> becomes backticks, and <pre> blocks become fenced code blocks. Simple tables convert to GitHub-flavoured Markdown tables.
What gets lost
Markdown has no colours, fonts, classes, or layout. Tables with merged cells or nested lists inside cells cannot be expressed. Embedded videos, forms, and scripts have no Markdown equivalent. A good converter either drops them or leaves raw HTML in place, since most Markdown renderers accept inline HTML.
Cleaning up first
Pages copied from the web carry navigation, cookie banners, and tracking wrappers. Extract only the main article before converting, and remove empty <span> and <div> wrappers left by visual editors. The less noise in the HTML, the cleaner the Markdown.
Check links and images
Relative URLs such as /images/photo.jpg break once the content moves. Convert them to absolute URLs or copy the assets alongside the Markdown, and make sure every image keeps meaningful alt text.