Why convert HTML to Markdown at all?
Markdown has quietly become the default format for anything text-heavy that humans edit: README files, documentation sites, wikis, issue trackers, and note apps all speak it. The catch is that the content you want frequently arrives as HTML — a page you are migrating, a CMS export, an email newsletter, a snippet copied from the web. Rebuilding that content as Markdown by hand is tedious and error-prone. Conversion does it mechanically, preserving the structure while shedding HTML’s syntax noise. The HTML to Markdown tool performs this transformation instantly in your browser.
What maps cleanly
Most of HTML’s meaningful structure has a direct Markdown equivalent, and a good converter handles each:
- Headings
<h1>–<h6>become#through######. - Paragraphs become blocks separated by blank lines.
- Emphasis —
<strong>/<b>become**bold**,<em>/<i>become*italic*. - Links
<a href="…">text</a>become[text](url). - Images
<img src="…" alt="…">become. - Lists —
<ul>and<ol>become bullet and numbered lines, with nested lists indented. - Blockquotes become
>prefixed lines. - Code —
<code>becomes inline backticks and<pre>becomes a fenced block.
Because these mappings are unambiguous, the conversion is deterministic: the same HTML always produces the same Markdown. Paste any of these structures into the HTML to Markdown tool and you can watch each one translate.
Lists and code: where converters earn their keep
The easy elements are easy; the interesting behaviour is in lists and code. A nested list — a <ul> living inside an <li> — must be indented under its parent item, using two spaces per level, which is the Markdown convention. Get the indentation wrong and the nesting collapses or the list breaks entirely. A robust converter tracks depth as it walks the tree so any level of nesting comes out correctly.
Code is the other careful case. The whole point of a code block is that its whitespace and characters are literal, so the converter must capture the content of <pre> and <code> verbatim rather than collapsing its whitespace the way it would for prose. It also should not try to interpret the angle brackets inside code as tags. Treating code as raw text is what keeps a snippet intact through the round trip.
What gets dropped — and why that’s correct
Not everything in HTML should survive. Three categories are removed entirely:
- Scripts and styles, because their contents are code, not content.
- Comments, because they are invisible and carry no reader-facing meaning.
- Presentational wrappers like
<span>,<font>, and layout<div>s, which have no Markdown equivalent. These are unwrapped: the text inside is kept, the tag is discarded.
Dropping these is a feature, not a loss. Markdown is intentionally a small, readable format; faithfully preserving every <div class="col-md-6"> would defeat the purpose. The goal is clean structure, and the HTML to Markdown converter optimises for exactly that.
Convert, strip, or format?
It is worth being clear about which tool solves which problem, because all three touch HTML:
- Convert keeps the structure in portable Markdown — this tool.
- Strip discards all formatting and returns plain text — the HTML Stripper.
- Format keeps the HTML but re-indents it for readability — the HTML Formatter, covered in our formatting guide.
The deciding question is what you want to keep: portable structure, just the words, or readable markup. Answer that and the choice is obvious.
A practical migration workflow
When you are moving a batch of pages into a Markdown-based system, a dependable routine is: convert each page, skim the Markdown for anything that came through oddly (usually exotic tables or deeply custom widgets), and fix those by hand. The bulk of the content — prose, headings, links, and lists — converts cleanly, so your manual effort is reserved for the genuine edge cases. Because the HTML to Markdown tool runs entirely client-side, you can convert sensitive content without it ever leaving your machine.
Round-tripping and its limits
A natural question once you can convert HTML to Markdown is whether the trip is reversible — can you turn the Markdown back into the same HTML? In practice the round trip is lossy by design, and understanding why prevents frustration. Markdown deliberately supports only a small, common subset of what HTML can express. A <div class="callout" data-analytics="hero"> carries class names, data attributes, and nesting that have no Markdown equivalent; converting to Markdown keeps the text and discards the rest. Convert that Markdown back to HTML and you get clean, generic markup — correct structure, but none of the original styling hooks.
This is usually exactly what you want. The reason to move content into Markdown is to shed presentation and keep meaning, so the loss of class attributes and wrapper divs is the point, not a bug. Problems only arise when people expect Markdown to preserve a pixel-perfect layout. It will not, and it should not.
There is a second subtlety around whitespace and line breaks. HTML collapses whitespace and uses tags for structure; Markdown uses blank lines and, for hard breaks, two trailing spaces. A converter has to translate between these two models, which is why a single <br> becomes two spaces and a newline, and why adjacent block elements become paragraphs separated by a blank line. The HTML to Markdown tool handles these conventions so the output renders the way you expect in any Markdown processor.
The practical guidance is to treat conversion as a one-way migration step, not a reversible format toggle. Convert once, review the Markdown, and from then on edit the Markdown as the source of truth. If you find yourself repeatedly converting back and forth, that is usually a sign the content should live in just one format — and for human-edited documentation, that format is almost always Markdown.
Key takeaways
HTML to Markdown conversion preserves the structure that matters — headings, emphasis, links, images, lists, blockquotes, and code — while dropping scripts, styles, comments, and presentational wrappers that have no place in Markdown. The careful parts are nested lists, which need correct indentation, and code, which must be captured verbatim. Choose conversion when you want portable structure, stripping when you want plain text, and formatting when you want readable HTML.