How HTML is converted to Markdown

A tree walk, not a text transformation

The browser doesn't hand a converter raw HTML text to pattern-match against; it hands over the DOM, the parsed tree structure the browser already built to render the page: this paragraph contains this bold span, which contains this text node, and so on. A converter walks that tree from the top down, and for every node it encounters, asks one question: what Markdown syntax represents this specific element? A `<strong>` becomes text wrapped in `**`, an `<h2>` becomes a line starting with `##`, an `<a>` becomes `[text](url)`. The output is built by recursively converting each node's children first, then wrapping the result in whatever syntax that node's tag calls for.

Why this is a mapping, not a translation

Every HTML element needs an explicit rule saying what Markdown it becomes; there's no automatic or general-purpose way to derive one from the other, because Markdown wasn't designed to represent everything HTML can. A `<div>` with a custom CSS class carries no Markdown equivalent at all; a converter simply treats it as an invisible wrapper and keeps its content. This is why a mature converter ships with dozens of built-in rules (one per common tag) and lets you register more for anything unusual it encounters.

Why a table needs a heading row to convert at all

Pipe-table syntax belongs to popular Markdown extensions, not the original core specification. A converter may infer the first row as a header, preserve a headerless table as raw HTML or use a dialect-specific representation. There is no universal requirement that makes conversion impossible without cells.

What never survives the trip

Colors, fonts, scripts, complex layout and many attributes lack portable Markdown equivalents. A converter may discard them, preserve raw HTML or use extensions according to its policy. Sanitization is a separate security concern, especially when untrusted HTML is involved.

What to inspect after conversion

Why does pasted content sometimes carry unexpected formatting? Rich-text paste from apps like Word or Google Docs often wraps content in extra styling elements the app added for its own rendering; a converter still extracts the underlying structure correctly, but very unusual source formatting can occasionally produce noisier output than clean HTML would.

A link with an empty label has no useful visible anchor. A converter may emit an empty Markdown link, use the URL as text or drop it, depending on its rules.

Is HTML-to-Markdown conversion reversible? Not perfectly; converting Markdown back to HTML recovers the structure, but anything Markdown couldn't represent in the first place (custom styling, layout) is already gone and can't be reconstructed from the Markdown alone.

Good conversion is a documented set of choices: which dialect to target, which HTML to preserve and which unsupported details to remove. Review tables, nested lists, code, images and links before publishing.