Converting HTML Back to Markdown Is Lossy, and Knowing What Is Lost Matters

Converting HTML to Markdown feels like it should be symmetric with the other direction. It is not, and the asymmetry is structural rather than a matter of implementation quality. HTML describes presentation, and Markdown describes structure. Anything that exists to control how something looks has nowhere to go when you convert.

That is not a reason to avoid the conversion. Prose, headings, lists, links, and code survive well, which covers most of what people actually want. It is a reason to know in advance which parts of your document will come back different, so you can plan for them rather than discovering them in the diff.

Key Takeaways

• HTML is presentation-oriented and Markdown is structure-oriented, so the reverse conversion cannot be lossless.
• Prose, headings, lists, links, and code come back well. Classes, IDs, inline styles, and layout do not.
• The HTML specification defines the elements and attributes this approach has to account for, and it is where the presentation-to-structure mismatch is most visible. The standard implementation is a whitelist converter such as Turndown rather than a generic serializer.
• Round-tripping is a good way to get an editable starting point, not a good way to preserve a design.

Why the Reverse Direction Cannot Be Lossless

Markdown was designed to be converted into HTML, not the other way around. The original Daring Fireball description frames it as a way of writing readable plain text that renders to HTML, and nothing in the design anticipates HTML as input.

The mismatch shows up as soon as you look at what each format can express. Markdown has no syntax for a CSS class, an element ID, an inline style, a grid layout, or a specific element like <figure> or <details>. The CommonMark specification defines what it does support, and the list of gaps is not short.

A converter therefore has two options when it meets a construct Markdown cannot express. It can drop it, or it can pass it through as raw HTML, which Markdown does permit. Most converters drop presentation and keep structure, with an option to preserve raw HTML for the cases where that is what you want.

What survives and what does not

The split is fairly clean, and knowing it in advance is most of the work.

HTML construct	After conversion
Paragraphs, headings	Preserved
Ordered and unordered lists	Preserved
Links and images	Preserved, with alt text
Inline code and code blocks	Preserved
Tables	Varies by converter
Classes and IDs	Dropped
Inline styles	Dropped
Layout elements and wrappers	Dropped or flattened
<figure>, <details>	Dropped or passed as raw HTML

The right-hand column is the part worth planning around. A document that uses a <figure> with a caption, or a <details> block for progressive disclosure, will come back with the content present but the structure flattened, which usually means the text survives and the semantics do not.

How converters actually work

The standard approach is not a generic HTML-to-text routine. It is a whitelist converter: a library that defines a set of rules mapping known HTML elements to their Markdown equivalents, and passes through or discards everything else.

Turndown is the most widely used client-side option, and its plugin model is the reason it handles real documents. A plugin is where you say what a custom element should become, which is how a converter that knows nothing about your site still produces sensible output for the specific markup you use.

The alternative is a generic serializer, which flattens by attribute count or text density. Those are heuristic and they lose the distinction between a heading and bold text at roughly the same size. A whitelist converter knows the difference because the HTML told it.

The CommonMark reference walks the syntax this is converting into. For a converter aimed at the reverse direction generally, the Mozilla CommonMark spec's guidance on raw HTML blocks is worth reading, since it defines where HTML is permitted in a Markdown document and therefore what a converter may emit.

Round-tripping is a real technique

Converting HTML to Markdown and back is genuinely useful, and the lossiness is usually not what people expect it to be. The common cases work well.

Migrating content out of a CMS into a repository is the clearest case, and the CommonMark project documentation describes the target format this is moving toward. The prose, structure, and links come across, and the presentation markup is being discarded deliberately anyway, because a Markdown repository should not carry the old site's CSS classes.

Starting a rewrite from existing markup is the second. Take a page, convert it, and edit the Markdown rather than fighting the original. Whatever presentation details are lost, you were going to replace them.

A third case is content extraction. A page with a lot of navigation and chrome, where you want the article body as clean Markdown. Here the loss of layout is the point rather than a compromise.

What round-tripping is not good for is preserving a design, and that is a property of the format rather than of any particular tool. A converter that tried to preserve presentation would produce raw HTML in the output, which is a different artifact from Markdown. If the presentation is the deliverable, converting to Markdown and back will not get you there, and the diff will be large enough that reviewing it costs more than rebuilding the styling.

Practical advice for the conversion

Three things make the difference between a clean result and a mess.

Convert prose-heavy content, not page chrome. A CMS page is mostly navigation, headers, and footers. Converting the whole document gives you all of that. Extracting the article body first gives you something worth keeping.

Review the output for tables and raw HTML. Tables are the most likely construct to come back differently, because a converter needs a rule for cell boundaries and borders carry no semantic information. Check them rather than assuming.

Do not round-trip a document you also need to keep rendering the old way. If the design matters, keep the original and treat the Markdown as a starting point for something new. Converting back and calling it equivalent is where the loss becomes expensive.

If you need the forward direction, the Markdown to HTML converter runs the other half of this pipeline in your browser, sanitizing the result so raw HTML in the source cannot inject scripts. And if your real goal is to strip dangerous markup rather than convert formats, the HTML Sanitizer / XSS Filter does that directly.

Related tools and further reading

The Markdown syntax cheat sheet covers what the target format can actually express, which is the reference for deciding whether a conversion will preserve a construct. The CommonMark specification is authoritative on both what Markdown supports and where raw HTML is permitted. For the security consequences of the forward direction, sanitizing Markdown output against XSS covers why the output needs sanitizing, and HTML escaping vs sanitizing distinguishes that from encoding. If you are choosing a format rather than converting between them, Markdown vs HTML covers when each one fits.