Convert HTML to Markdown

Where HTML to Markdown conversion runs out of syntax

Markdown was designed to be readable as plain text, which means it deliberately holds less vocabulary than HTML. There is no syntax for a merged table cell. None for a superscript, a definition list, two columns, centered body text or a colored word. HTML has all of them. Every conversion therefore reaches a point where something in the source has no destination, and what happens at that point is the entire difference between one converter and another.

Three honest answers exist. Keep the original HTML, which is legal inside a Markdown document and is what CommonMark expects. Reduce the construct to plain text and accept the loss. Or say nothing and hand back something broken. The third is the common one: a table with a colspan run through a careless converter comes out as a pipe table with every cell below the merge shifted one column to the left. The file is valid Markdown, the data is wrong, and nothing on screen tells you.

This tool takes the first answer by default and the second on request, and it reports either way. Beside the output sits a list of what could not be carried — one line per construct, with a count, in words rather than element names: merged cells, a nested table, a line break inside a cell, more than one header row. When that list is empty the tool says so outright, which is worth as much as any of the warnings.

The parts of a page that quietly change shape

Beyond tables, the constructs that reach people most often are inline.<sup> and <sub> in anything scientific, legal or financial. <kbd> in documentation. <abbr>,<mark>, <u>, <time>. Not one of them has a Markdown spelling, so they stay as inline HTML unless you switch the setting to stripping. The same holds for definition lists and for collapsible<details> blocks, where the content between the tags is still converted to Markdown, so the folded section keeps working where the surrounding document does.

A second group cannot be kept in any form and is simplified instead. Multi-column layouts flatten to a single column. Text alignment survives in table columns and nowhere else. Color, <font> and image dimensions have nothing to attach to. A figure caption becomes the paragraph after the image, a table caption becomes the paragraph above the table, and an embedded video or iframe becomes a link to its source instead of disappearing. A table with no header row has its first row promoted into one, because a Markdown table always has a header. All of it is named on the report.

Formatting that exists only in a style attribute is treated as content rather than decoration. Word writes bold as<span style="font-weight:700"> rather than<b>, and Google Docs wraps an entire exported document in<b style="font-weight:normal">. Without both of those special cases a pasted document comes back either wholly unformatted or wholly bold.

Two ways to paste, and the second is the one most people want

Pasting HTML source is the obvious route: the text you paste is the tags themselves, taken from a source view, a template file or an export.

Pasting from a page is the other one. When you select part of a rendered web page and copy it, your clipboard does not hold the visible characters alone — it also holds atext/html representation of the selection, with the headings, links, lists and tables intact. This tool reads that flavor and converts it, so turning an article, a documentation page or a rendered README into Markdown costs a copy and a paste, with no source view anywhere in the sequence. Both routes are on the page as equals, and.html files open through the file picker as a third. If what you want is the formatting gone entirely rather than translated, the text cleaner is the shorter road.

What is removed before a single character is written

Scripts, stylesheets, <noscript>, <template>,<canvas>, <svg>, <math>, forms and form controls do not survive, and no on… event attribute is ever written out — not in the plain Markdown and not inside the HTML that is kept. Link and image destinations are checked against a list of schemes that are allowed rather than a list that is forbidden, so a javascript: target keeps its text, loses its link, and turns up on the report.

This matters more than a converter's output usually does, because Markdown is seldom the last stop. It gets rendered back into HTML later by a site generator, a README viewer or a comment field — the same problem seen from the other direction onthe Markdown to HTML converter. Anything that slipped through here would be live markup there. The HTML that is kept comes from a short list of permitted tags carrying a short list of permitted attributes, which is why the round trip between the two tools cannot bring back something that runs.

What this tool does not do

It does not fetch a URL for you. There is no address field: you paste the page or open the file, which is also the reason nothing has to be sent anywhere. It does not repair bad HTML either — unclosed tags, stray end tags and mis-nesting are read as they stand and noted rather than rewritten, and reshaping a document as HTML belongs tothe HTML formatter. And it does not guess at intent. A<div> that looks like a callout comes out as a paragraph, because CommonMark has no callout and inventing one would put text in your document that the source never contained.

Nothing you paste leaves this tab. The conversion is JavaScript running in the page you are reading, on text your browser already holds, and this site has no endpoint that accepts it — so there is no copy of your document to store and no address to log. The claim is checkable in about ten seconds: open your browser's developer tools, switch to the Network panel, and paste. The traffic list stays exactly as long as it was.