Why convert HTML to Markdown
- Migrating a CMS — moving posts out of WordPress, Drupal or a bespoke database into a static-site generator (Hugo, Eleventy, Astro) that stores content as Markdown files.
- Cleaning pasted rich text — text copied from Word, Google Docs or a web page arrives wrapped in
spansoup with inline styles. Converting to Markdown and back gives you clean, minimal markup. - Documentation pipelines — tools like Docusaurus, MkDocs and mdBook take Markdown as source. Converting existing HTML docs is the first migration step.
- Version control — Markdown diffs are readable line by line; an HTML diff usually is not.
- Feeding an LLM or a search index — Markdown keeps the structure (headings, lists, links) while dropping the presentational noise.
What each element becomes
| HTML | Markdown |
|---|---|
<h1> … <h6> | # … ###### |
<p> | A paragraph separated by a blank line |
<strong>, <b> | **text** |
<em>, <i> | *text* |
<del>, <s>, <strike> | ~~text~~ |
<a href> | [text](url) |
<img src alt> |  |
<code> (inline) | `code` |
<pre> / <pre><code> | A fenced code block |
<ul> / <ol> / <li> | - or 1. items, indented when nested |
<blockquote> | > prefix |
<hr> | --- |
<br> | A hard line break |
<table> | A pipe table (simple tables only) |
<div>, <span> | Unwrapped — text kept, tag dropped |
<script>, <style>, comments | Removed |
What does not round-trip cleanly
Markdown is a small language. When the source HTML uses something it cannot express, information is lost or the converter falls back to raw HTML:
- Complex tables —
colspan,rowspan, multiple block elements in a cell, or a caption. Pipe tables are a single line of text per cell. - Nested inline formatting — a link inside bold inside a heading usually works, but unusual combinations can produce awkward output.
- Presentational markup — colors, font sizes, alignment, custom classes and
styleattributes have no Markdown equivalent and are dropped. - Custom or semantic HTML —
<figure>/<figcaption>,<details>,<abbr>, footnote markup and web components are flattened to their text.
If a clean round trip matters, convert, then render the Markdown back and compare it to the original.
Common questions
Why convert HTML to Markdown?
Migrating a CMS to a static-site generator, cleaning rich text pasted from a word processor, feeding a docs pipeline, and getting readable diffs in version control.
What does not round-trip cleanly?
Merged table cells, multi-paragraph cells, colored or sized text, custom classes, figures with captions, and deeply nested inline formatting.
What happens to scripts and styles?
script, style, noscript and comments are removed. div and span are unwrapped so their text survives without the tag.
Full page or fragment?
Both. A whole document is read from its body; a fragment is treated as body content. Head elements are ignored.
Is my HTML uploaded?
No. It is parsed with the browser's DOMParser and walked locally.