HTML to Markdown Converter

What conversion can and cannot preserve

Markdown is deliberately smaller than HTML. It has constructs for headings, emphasis, links, images, lists, blockquotes, code and, with GFM, tables. It has nothing for colspan, inline styling, arbitrary attributes, forms, iframes or nested layout. Converting HTML to Markdown is therefore lossy by design, and the useful question is which losses are acceptable.

This converter maps structural elements to their Markdown equivalents and discards purely presentational wrappers. A <div> used for layout disappears; the text inside it survives. A <span style="color:red"> loses the colour and keeps the words. That is the correct behaviour: if you needed the colour, you needed HTML.

The pasted-from-Word problem

The most common input to a converter like this is HTML copied out of a word processor or a CMS editor. That markup is typically dense with nested spans, inline styles, conditional comments and class names that mean nothing outside the originating application. Converting it is really an exercise in throwing almost all of it away. The result is usually dramatically shorter than the input, which is the point.

Tables and nesting

Simple rectangular tables convert cleanly to GFM pipe tables. Tables using rowspan or colspan have no Markdown representation at all, and any converter must either flatten them, losing the merge, or emit raw HTML. Nested tables, still common in email templates, cannot be represented and are best handled by keeping the HTML.

Escaping matters

Text content that happens to contain Markdown syntax must be escaped or it will be reinterpreted on the next render. A literal asterisk, underscore, backtick or square bracket in body text needs a backslash in front of it, otherwise a product name like file_name_here renders with an italic run in the middle. Converters that skip this step produce output that looks fine until it is rendered.

Local conversion

Parsing uses the browser's own HTML parser, so the structure you get is exactly what a browser sees. Nothing is uploaded, which matters when converting internal documentation or client work.