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 report describes the Markdown that is actually written, including its final word count. Non-breaking and typographic spaces remain characters rather than being mistaken for disposable source indentation. A malformed document never receives the clean verdict: its tags are read as written, its parser issues stay visible, and a conversion that cannot finish removes the previous result instead of leaving the wrong file ready to copy or download.

When conversion is the starting point rather than the final artifact, copy the result into the Markdown editor to revise headings and prose in Styled view while retaining Raw source and a .md download. This converter remains the place to change HTML-specific policies and inspect loss.

HTML and Markdown, in brief

HTML

Full name	HyperText Markup Language
Extension	.html, .htm
Format type	Markup document
MIME type	text/html

Markdown

Full name	Markdown
Extension	.md, .markdown
Format type	Plain text with lightweight formatting
MIME type	text/markdown

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.

If the table itself is the whole job and the destination is a spreadsheet, the HTML table to CSV converter is the more exact route: it draws every rowspan and colspan before asking how those merged positions should be represented in CSV, Excel or pipe Markdown.

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.

Convert a webpage to Markdown without fetching its URL

The current-page bookmarklet handles the case a URL box cannot: a signed-in article, a client-side view, or the exact selection already on screen. Run it in that tab. If text is selected, the selection is the source. Otherwise it chooses the largest <article>, then <main>, then the page body. The collector removes scripts, styles, forms and hidden controls, resolves relative links against the page, and sends the chosen HTML directly back to this editor.

Title, source URL, exposed byline and publication date arrive as a separate receipt. They can be included as YAML front matter in the downloaded Markdown or switched off. The content itself remains editable, and it goes through the same unsafe-URL checks and loss report as pasted source. This is one mode of the existing converter, not a second page competing for the same job.

To curate several published Markdown resources into one concise machine-readable guide, use the llms.txt generator. It accepts visible fields, a URL list or local sitemap XML and never fetches the linked pages or invents summaries.

Two ways to paste when a bookmarklet is not the right route

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 a text/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 tags and active subtrees gone entirely rather than translated, use the HTML to text converter. The text cleaner instead starts after extraction, with plain text that needs whitespace or character cleanup.

A rich paste from Word or Google Docs is identified from the HTML that actually reached the browser, and the intake receipt names unresolved clipboard-only images and Word list styling instead of guessing. When exact DOCX numbering, notes and embedded image bytes matter, use the Word to Markdown converter; its verified ZIP keeps local asset paths together with the Markdown.

Native Word and Google Docs clipboard access was not available in the automated test environment. The conformance tests therefore use synthetic browser DataTransfer flavors that reproduce the observed text/html and text/plain boundary; they prove flavor precedence and reporting, not a live copy gesture from either desktop application.

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 on the 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 clip the open page, paste it or open the file, which is also the reason no crawler or proxy is involved. 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 to the 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.

Nor does it open an archive. An EPUB is a zip of XHTML chapters, which is HTML by any other name, but unpacking one and putting the chapters back in reading order is a separate job with a separate answer in the EPUB to PDF converter.

Nothing you paste is uploaded. Bookmarklet content moves directly from the source tab to this tab with an origin-bound browser message, or through the JSON file you download; this site has no endpoint that accepts the document. The conversion is JavaScript over text your browser already holds. Open the Network panel before pasting or importing and the conversion adds no document request.