How to Convert HTML to Markdown

Markdown is HTML stripped down to its readable core: the same headings, links, lists, and emphasis, expressed in plain-text symbols instead of angle-bracket tags. Converting HTML to Markdown gives you a clean, version-control-friendly document that is easy to read in a plain editor, quick to edit, and simple to republish anywhere Markdown is understood, from a README to a static-site generator.

The catch is direction. HTML can express far more than Markdown can, so this conversion is a deliberate simplification. You keep the content and structure while shedding the presentation. This guide shows exactly what maps cleanly, what gets flattened, why the trip is one-way, and how to run the conversion without uploading anything.

Trading tags for symbols

HTML describes a page with nested tags and attributes; Markdown describes the same ideas with a handful of punctuation marks. A converter walks the HTML structure in reading order and rewrites each element into its Markdown counterpart, so a page of headings and paragraphs becomes a tidy text file that still reads clearly even before it is rendered back to HTML.

Two markup languages, two goals

HTML, the HyperText Markup Language, is the foundational document format of the web, maintained today as a living standard and documented in depth by MDN.^[2] It is enormous in scope: it can describe not just text and structure but styling hooks, forms, embedded media, scripting, and accessibility semantics. The Library of Congress catalogs it as a broad format family precisely because it has evolved through many versions while remaining backward compatible.^[1] HTML's power is that it can express almost anything a page needs.

Markdown was created in 2004 by John Gruber, with Aaron Swartz, as a deliberately tiny language: a way to write structured text using punctuation that stays readable as plain text.^[4] Its guiding principle is that the source should look like what it means, so a heading is marked with a hash and a list with a dash. It has since been standardized as a media type, registered as text/markdown in RFC 7763, which formally acknowledged the many flavors that had grown up around the original.^[3] The two formats sit at opposite ends of a spectrum: HTML is exhaustive and machine-oriented, Markdown is minimal and human-oriented. Converting down from one to the other means keeping the ideas both can express and letting go of everything only HTML can.

How the conversion works under the hood

A good HTML-to-Markdown converter does not treat the file as text to search and replace; it parses it. First it builds a document tree from the HTML, the same structure a browser builds, so it understands which elements are nested inside which. Then it walks that tree in reading order, visiting each node and emitting the Markdown equivalent: a heading node becomes hashes, a strong node wraps its text in asterisks, an anchor node becomes bracketed link syntax carrying the same destination.

Two decisions make the difference between a clean result and a messy one. The converter must decide what to do with elements that have no Markdown equivalent, and the well-behaved answer is to emit the original HTML inline, because Markdown by design permits raw HTML to pass through untouched. It must also normalize whitespace, collapsing the incidental spacing of source HTML into the blank-line conventions Markdown uses to separate paragraphs and blocks. When those two things are handled well, the output reads as if it had been written in Markdown from the start.

Parsing rather than search-and-replace is what makes this robust. A naive tool that just swapped tags for symbols with regular expressions would break the moment it met nested emphasis, an attribute containing angle brackets, or a malformed but browser-tolerated page. Building the document tree first means the converter understands structure the way a browser does: it knows that an anchor inside a list item inside an ordered list is three levels of nesting, and it can emit the list marker, then the link syntax, in the right order. It also lets the tool escape characters that would otherwise be misread, so a literal asterisk or backtick in your text does not accidentally turn into Markdown formatting. Those safeguards are the difference between output you can publish immediately and output you have to hand-repair.

How HTML maps to Markdown

Most structural HTML has a direct Markdown equivalent, so the conversion is predictable for ordinary documents.

Why the Markdown flavor matters

There is no single Markdown. John Gruber's original 2004 syntax deliberately left many things unspecified, and over the years communities filled those gaps with their own extensions, producing several widely used flavors.^[4] The most common today is GitHub Flavored Markdown, which adds tables, fenced code blocks, task lists, and strikethrough on top of the core. CommonMark is a separate effort to pin down a precise, unambiguous specification for the base syntax. This fragmentation is exactly why the format was eventually registered as the text/markdown media type in RFC 7763, which formally acknowledges that a given Markdown document is written for a particular variant and carries an optional parameter to say which one.^[3]

The practical effect on conversion is that some HTML features only survive if the target flavor supports them. A data table, for instance, has no home in the original Markdown syntax but maps cleanly to a GitHub Flavored Markdown table. A good converter targets a widely understood flavor, typically GitHub Flavored Markdown, so that headings, tables, code fences, and task lists all come through. If your destination uses a stricter parser, features it does not recognize will either render as literal text or fall back to inline HTML. Knowing which flavor your Markdown will be read in tells you in advance which parts of a rich HTML page will survive as real Markdown and which will pass through as raw tags.

Convert HTML to Markdown, step by step

1. Open the converter and add your HTML

   Open the FileFormer document converter and drop in your HTML file. It runs on your device, so your content is never uploaded.

2. Choose Markdown as the output

   Set the target to Markdown. The converter will rewrite the tags into symbols while keeping the reading order.

3. Convert

   Headings, emphasis, links, lists, and code blocks become Markdown; inline CSS, classes, and scripts are dropped.

4. Download and tidy

   Save the .md file and skim it once. Any complex table or layout that could not map cleanly is where you may want a quick manual fix.

What gets simplified or dropped

Markdown is intentionally minimal, so anything visual or interactive in the HTML is removed: inline CSS and classes, JavaScript, forms, and elaborate nested layouts all disappear, leaving the underlying content. Simple tables convert to Markdown table syntax, but advanced features like merged cells have no equivalent. When a converter meets HTML that Markdown cannot express, good tools fall back to leaving that snippet as inline HTML inside the Markdown, which most Markdown renderers still display correctly.

This is a slightly lossy, one-way trip. If you later need the styled page back, converting Markdown to HTML rebuilds the tags but not the original CSS. Keep the source HTML if the exact visual design matters, and treat the Markdown as the editable content copy. To go the other direction, see converting Markdown to HTML.

Why this trip is one-way

It is worth being precise about why you cannot simply round-trip a page through Markdown and get the original back. The reason is that HTML carries far more information than Markdown can express, and the conversion throws the surplus away rather than storing it somewhere.^[2] HTML, maintained today as a living standard, can describe class names, inline and linked CSS, data attributes, ARIA accessibility roles, custom elements, embedded scripts, and precise nesting, none of which have any representation in Markdown's small vocabulary.^[1] When the converter walks the tree and meets a styled <div> with three classes and an inline color, it keeps the text inside and discards the wrapper, because Markdown has no way to record that the wrapper ever existed.

So converting Markdown back to HTML later cannot reconstruct what was never written down. The rebuilt HTML will have clean, default headings and paragraphs, but the original layout, colors, fonts, and interactivity are simply gone. This is not a flaw in any particular tool; it is a direct consequence of moving from a large, expressive language to a small, readable one. The correct mental model is that Markdown is the content extracted from the HTML, not a compressed copy of the page, so the source HTML remains the only complete record of how the page actually looked.

Real-world scenarios and what to expect

How cleanly a page converts depends heavily on what kind of page it is. A few common cases:

The pattern is clear: the more a page is really an article, the better it converts, and the more it is really an application, the less of it Markdown can carry.

A few practical habits make the results cleaner regardless of the source. Convert the main content region rather than the whole page when you can, since site navigation, sidebars, cookie banners, and footers all flatten into stray lists and links that clutter the output. Skim the result for long runs of inline HTML, which mark the exact spots where the source contained something Markdown could not express and where a quick manual edit pays off. And decide early where the Markdown will be read, because a file bound for a GitHub README, a static-site generator, or a documentation tool each expects slightly different conventions, and matching that destination up front saves reformatting later. Treated this way, HTML to Markdown becomes a reliable first pass that turns a designed page into editable text you can polish in minutes.

When Markdown is the wrong target

Markdown is the right destination when you want lightweight, editable, version-controllable text. It is the wrong one when the visual design or interactivity is the whole point. If you need a page frozen exactly as it looks, with its fonts, colors, and layout preserved for printing or archiving, convert it to a fixed document with HTML to PDF instead. And if you simply want to keep editing the styled page as a web page, the best thing to keep is the original HTML itself, since no down-conversion can recover the CSS later. Treat Markdown as the clean content layer, not a replacement for the designed page.