Why convert HTML to Markdown?
Markdown is simpler to write and read than HTML. You might need to convert HTML to Markdown when:
- Migrating content from an HTML website to a Markdown-based platform (Ghost, Hugo, Jekyll)
- Converting a web page to a README file on GitHub
- Moving content from an old CMS to a new one
- Simplifying HTML email templates for editing
HTML to Markdown conversion table
| HTML | Markdown |
|---|---|
<h1>Title</h1> |
# Title |
<h2>Title</h2> |
## Title |
<strong>text</strong> |
**text** |
<em>text</em> |
*text* |
<a href="url">link</a> |
[link](url) |
<img src="x" alt="y"> |
 |
<ul><li>item</li></ul> |
- item |
<ol><li>item</li></ol> |
1. item |
<blockquote>text</blockquote> |
> text |
<code>code</code> |
`code` |
<hr> |
--- |
Markdown advantages over HTML
Readability: Markdown source is readable as plain text without rendering.
Portability: Works in GitHub READMEs, static site generators, Notion, Obsidian, and dozens of CMS platforms.
Speed: Writing ## Heading is faster than <h2>Heading</h2>.
What doesn't convert cleanly
HTML supports many features that have no Markdown equivalent:
<div>,<span>,<section>— structural elements with no Markdown equivalent (kept as raw HTML)<table>— converts to Markdown table format (supported in GitHub Flavored Markdown)- Inline styles (
style="color: red") — stripped entirely <script>and<style>tags — stripped- Complex nested structures — may require manual cleanup
When to keep raw HTML inside Markdown
Markdown parsers (including GitHub, Jekyll, Hugo) allow raw HTML inline. If you need something Markdown can't express — centered text, colored spans, custom classes — you can include the HTML directly:
Normal Markdown paragraph.
<p style="text-align: center;">Centered via HTML</p>
Back to Markdown.
Platforms that accept Markdown
- GitHub — READMEs, issues, pull requests, wikis
- Ghost CMS — native Markdown editor
- Hugo / Jekyll / Eleventy — static site generators
- Notion — supports Markdown shortcuts
- Obsidian — Markdown-native note taking
- Dev.to / Hashnode — developer blogging platforms
How to convert HTML to Markdown free
- Go to HTML to Markdown
- Paste your HTML in the left panel
- Markdown output appears instantly on the right
- Toggle preview to see rendered output
- Copy Markdown or download as
.mdfile
The conversion is lossy by definition
HTML can express things Markdown cannot, so converting always discards information. Knowing what disappears prevents unpleasant surprises.
| HTML | Fate in Markdown |
|---|---|
class, id, style |
Lost entirely |
<table> with colspan |
Flattened or broken — Markdown tables have no cell spanning |
<div>, <section>, <span> |
Dropped; only content survives |
| Nested tables | Not representable |
<sup>, <sub>, <abbr> |
Kept as raw HTML, or lost |
<video>, <iframe> |
Kept as raw HTML, or lost |
| Definition lists | Not in standard Markdown |
Tables with merged cells are the most frequent casualty. Markdown's table syntax has no equivalent of colspan or rowspan, so a converter must either flatten the structure — changing the meaning — or leave the HTML untouched.
Cleaning up converted output
Real-world HTML from a CMS or website carries wrapper markup that produces noisy Markdown. Typical cleanup:
Collapse nested emphasis. <strong><em>text</em></strong> becomes ***text***, which is valid but often unintended.
Fix heading levels. Pages frequently use <h1> for a site title and <h2> for the article title. In a standalone Markdown document the article title should be #, so shift every level up by one.
Remove tracking parameters. Links copied from a page often carry ?utm_source=.... These are meaningless in a document and clutter the source.
Delete empty emphasis. ** ** and __ __ appear where the source had styled whitespace, and render as stray asterisks.
Round-tripping does not round-trip
Converting HTML to Markdown and back does not return the original. Attributes, wrappers, and non-representable structures are gone at the first step and cannot be reconstructed.
This matters for anything that treats Markdown as canonical storage. If a CMS stores Markdown but users paste formatted content from Word or a web page, every paste silently drops formatting. That is often the right trade — it enforces consistency — but it should be a decision rather than a surprise.
Sanitise before converting untrusted HTML
HTML from an external source may contain scripts, event handlers, or javascript: URLs. Some converters preserve raw HTML they cannot represent, which carries those payloads into the Markdown — and if that Markdown is later rendered with raw HTML enabled, the script executes.
Sanitise the HTML first, or configure the converter to strip rather than preserve unknown tags. Never assume the Markdown step neutralises anything.
Frequently asked questions
Which Markdown dialect does the output use?
GitHub Flavored Markdown, since it supports tables and strikethrough that plain CommonMark lacks. Output pasted into a strict CommonMark renderer may show tables as literal pipes.
Why do some HTML tags remain in my Markdown?
Because Markdown has no equivalent. <sup>, <iframe>, and <details> are commonly preserved as raw HTML — which is valid, since most Markdown renderers pass HTML through.
Can I convert a whole web page?
You can paste the full HTML, but expect substantial navigation, footer, and sidebar noise. Copy just the article element for a usable result.
Does it handle inline styles?
No. style="color: red" has no Markdown representation and is dropped. Markdown deliberately separates content from presentation.
Is my HTML sent to a server?
No. Conversion runs entirely in your browser, so internal documentation and client content stay on your device.