HTML to Markdown: When and Why You'd Convert the Other Direction
Why people convert HTML back to Markdown, what survives the round trip, and the edge cases that trip up most converters.
Most people convert Markdown into HTML. Going the other way feels backwards until you actually need it — and then you need it badly.
Here’s the situation that usually triggers it: you copied something from a web page, a Google Doc, or an old CMS, and now you want it in a .md file. Paste the raw HTML into your README and you get a wall of <div> and <span> noise. What you wanted was a heading, two paragraphs, and a list. That’s the job an HTML to Markdown converter does — strip the markup down to the few characters Markdown actually uses.
Where this comes up
I keep running into the same handful of cases.
Migrating a blog is the big one. WordPress, Ghost, and most legacy platforms store posts as HTML. Move to a static site like Astro or Hugo and you want Markdown source files instead. Converting the exported HTML gets you 90% of the way there — you’ll still hand-fix a few posts, but you’re editing, not retyping.
Then there’s scraping content you’re allowed to keep. Documentation you wrote, an article you published, notes trapped in some web app’s rich-text editor. The HTML is fine for a browser and miserable to edit by hand.
And the small daily annoyance: you copy a table from a web page and need it in a Markdown doc. Retyping a ten-row table is the kind of task that makes you close the laptop. A converter turns it into a GitHub-flavored table in one paste.
What actually survives the conversion
Not everything maps cleanly, and it helps to know the boundaries before you trust the output.
These convert reliably:
- Headings
<h1>through<h6> - Bold, italic, strikethrough, and inline code
- Links and images
- Ordered and unordered lists, including nested ones
- Blockquotes and horizontal rules
- Code blocks — and if the
<code>tag carriesclass="language-js", the fence keeps thejstag
Tables are the interesting case. There’s no “right” way to put a complex HTML table into Markdown, because Markdown tables can’t do merged cells or block content inside a cell. A good converter flattens each cell to plain text, treats the first row as the header, and escapes any | characters so the result doesn’t fall apart. For ordinary data tables that’s exactly what you want. For a table someone used as a page layout — that was never going to translate, and no tool will save it.
The edge cases that bite
Whitespace is the quiet troublemaker. HTML collapses runs of spaces and newlines when it renders; your text editor doesn’t. A converter that copies whitespace literally produces Markdown full of stray indentation that your Markdown parser then reads as code blocks. The fix is to collapse whitespace the way a browser would — which is what the HTML to Markdown tool does before it emits anything.
Scripts and styles are the other one. A copied page fragment often drags in <script> and <style> blocks. You don’t want their contents showing up as text in your document, so they get dropped entirely rather than converted.
And unknown tags — all those <div>, <section>, and <figure> wrappers — get unwrapped. The tag disappears, the text inside stays. That single rule is what turns a bloated page fragment back into something readable.
Round-tripping isn’t lossless
One thing to keep in mind: Markdown → HTML → Markdown won’t always hand you back the exact file you started with. HTML has more ways to express the same thing than Markdown does, so a converter has to pick one. Bold might come back as ** when you originally wrote __. That’s cosmetic — the rendered result is identical — but don’t expect a byte-for-byte match.
For a one-off paste, none of this matters. For bulk migration, run a few representative pages through first and eyeball the output before you convert a thousand.
Paste your HTML into the HTML to Markdown converter and copy clean Markdown straight out — no signup, nothing to install.