HTML to Markdown: How to Convert Web Pages & Rich Text (2026)
Convert HTML, Word exports, and CMS content to clean GitHub Flavored Markdown — browser tools, CLI, API pipelines, and cleanup workflows for migrations and AI output.
Every team eventually needs to turn HTML into Markdown: migrating a WordPress blog to Hugo, cleaning a Notion export, converting legacy Confluence pages, or normalizing HTML that an AI model returned when you asked for Markdown.
The conversion is never perfect — HTML encodes layout and styling that Markdown deliberately omits. But good HTML-to-Markdown produces editable, diff-friendly GFM you can commit to Git, not a soup of <div> wrappers and inline styles.
This guide explains how conversion works, compares five approaches, and walks through cleanup workflows for the messiest real-world inputs.
Why convert HTML to Markdown?
| Motivation | Benefit |
|---|---|
| Docs-as-code | .md files in Git with clean PR diffs |
| CMS migration | Leave WordPress/Webflow → static site |
| Knowledge base cleanup | Notion/Confluence → Obsidian or repo |
| AI pipeline hygiene | Models often return HTML despite prompts |
| Email / newsletter archive | HTML newsletters → searchable text |
| Scraping & research | Web pages → notes in a vault |
Markdown is the interchange format. HTML is the delivery format. Converting HTML → Markdown is how you reclaim portability.
What converts cleanly (and what does not)
Converts well
<h1>–<h6>→#headings<p>→ paragraphs<strong>,<b>→**bold**<em>,<i>→*italic*<a href>→[text](url)<ul>,<ol>,<li>→ lists<pre><code>→ fenced code blocks<table>→ GFM pipe tables (when structure is simple)<blockquote>→> quote<del>,<s>→~~strike~~
Converts poorly
| HTML pattern | Problem | Manual fix |
|---|---|---|
Nested <div> layout | No Markdown equivalent | Strip wrappers |
<span style="..."> | Inline CSS lost | Accept loss or use HTML in MDX |
| Complex colspan tables | GFM has no colspan | Simplify table or use HTML in MDX |
<iframe> embeds | Becomes link or drops | Replace with  + link |
| Custom web components | Unknown tags | Remove or replace with text |
spacing | Odd whitespace | Run formatter |
Set expectations: conversion is 80% automated, 20% editorial.
Method 1: Browser converter (fastest)
For one page or paste buffer:
- Open HTML to Markdown.
- Paste HTML source (View Source, DevTools copy, or export file).
- Copy GFM output or download
.md.
The tool preserves tables, fenced code language hints, links, images, and task lists where the HTML structure allows.
Pros
- Instant — no CLI install.
- Private — runs client-side in the tool.
- Free — no account required.
Cons
- One document at a time
- Very large pages may need splitting
When to use
Support ticket cleanup, single blog post migration, "I copied HTML from Gmail."
Method 2: Turndown (JavaScript library)
Turndown is the de facto HTML→Markdown library for Node and browsers.
import TurndownService from "turndown";
import { gfm } from "turndown-plugin-gfm";
const turndown = new TurndownService({
headingStyle: "atx",
codeBlockStyle: "fenced",
});
turndown.use(gfm);
const markdown = turndown.turndown(document.querySelector("#content")!.innerHTML);
Custom rules
turndown.addRule("strikethrough", {
filter: ["del", "s"],
replacement: (content) => `~~${content}~~`,
});
Pros
- Embeddable in apps, extensions, scrapers
- Plugin ecosystem — GFM tables, task lists
Cons
- You configure edge cases — every CMS has quirks
- No sanitization — scrub HTML before turndown on untrusted input
When to use
Browser extensions, crawlers, CMS import wizards.
Method 3: Pandoc
pandoc page.html -f html -t gfm -o page.md
Batch a folder:
for f in export/*.html; do
pandoc "$f" -f html -t gfm -o "md/$(basename "$f" .html).md"
done
Pros
- Batch — hundreds of files in a shell loop
- Format detection — handles some Word exports
Cons
- Table fidelity varies — complex layouts break
- Wrapper noise — full HTML documents include
<head>junk unless you extract<body>first
When to use
Academic archives, ebook pipelines, ops teams on Pandoc already.
Method 4: REST API (production)
For server-side pipelines — CMS webhooks, AI output normalization, user paste endpoints:
curl -X POST https://trymarkdownviewer.com/api/v1/convert/html-to-markdown \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"html": "<h1>Title</h1><p>Hello <strong>world</strong>.</p>"}'
Response:
{
"markdown": "# Title\n\nHello **world**."
}
The API strips <script>, <style>, and <noscript> automatically — important for scraped or user-submitted HTML.
Related endpoints:
- Format Markdown — normalize whitespace after conversion
- Validate — catch broken output before commit
- Extract links — audit URLs post-migration
Test in the API playground. Docs: HTML to Markdown endpoint.
Pros
- Consistent with browser tool — same conversion logic
- No parser in your app — offload CPU and CVE tracking
- CI-friendly — call from GitHub Actions on migration branches
Cons
- Payload size limits — split huge HTML documents
- API quota — plan limits apply
When to use
Multi-tenant importers, AI chat sanitization, automated migration jobs.
Method 5: Manual cleanup + smart tools
Automated conversion plus targeted fixes beats either alone.
Cleanup pipeline
HTML source
→ convert (tool / API / Turndown)
→ [formatter](/tools/markdown-formatter)
→ [heading audit](/tools/markdown-heading-audit)
→ [link checker](/tools/markdown-link-checker)
→ [GFM checklist](/tools/markdown-gfm-checklist)
→ commit
Typography pass
CMS HTML is full of smart quotes, em dashes, and non-breaking spaces. Run the typography cleaner or API transform typography after conversion.
Redact before publishing
Migrated pages may contain internal URLs, API keys in examples, or PII. Use redact tool before opening a public PR.
Source-specific migration playbooks
WordPress
- Export XML or use a static crawl of rendered pages.
- Extract
<article>or.entry-contentHTML per post. - Convert each to
.mdwith frontmatter:
---
title: "Post title"
date: 2024-03-15
slug: post-title
---
- Map
wp-content/uploads/images tostatic/images/and fix paths.
Notion
Notion Export → Markdown is the first step, but exports are messy. For HTML clipboard content:
- Paste into HTML to Markdown.
- Replace Notion callout remnants with callout syntax.
- Fix internal
[[links]]manually — see Notion guide.
Confluence
Confluence storage format is XML, not HTML. Export HTML view or use a dedicated migrator, then:
- Remove
<ac:structured-macro>artifacts - Convert expand/collapse sections to
<details>or headings - Simplify multi-column layouts
Google Docs
File → Download → Web Page (.html) produces verbose HTML. Convert, then:
- Strip
<span>noise with formatter - Replace numbered lists that became paragraphs
- Re-insert code blocks manually — Docs destroys fenced code
AI model output
Models often return:
<h2>Summary</h2><p>Here is <strong>bold</strong> text.</p>
when you asked for Markdown. Pipe through HTML-to-Markdown in your agent pipeline instead of re-prompting — cheaper and more reliable.
Tables: the hardest part
HTML tables with colspan, rowspan, or nested <div> inside cells rarely become valid GFM. Strategies:
- Simplify — one header row, one data row per concept.
- Split — one wide table → multiple narrow tables.
- Keep HTML — in MDX/Docusaurus, leave
<table>inline. - Rebuild — use table generator from CSV export.
Test tables with table ↔ CSV if you have spreadsheet exports.
Images and assets
HTML:
<img src="https://cdn.example.com/photo.jpg" alt="Dashboard">
Becomes:

Migration checklist for images:
- Download hotlinked images to repo
static/folder - Update relative paths:
 - Add alt text where HTML had empty
alt="" - Run image inventory via API on the converted corpus
Comparison table
| Method | Speed | GFM tables | Batch | Sanitizes HTML | Cost |
|---|---|---|---|---|---|
| Browser tool | ⚡⚡⚡ | ✅ | ❌ | ✅ | Free |
| Turndown | ⚡⚡ | ⚠️ | ✅ | ❌ | Free |
| Pandoc | ⚡⚡ | ⚠️ | ✅ | ❌ | Free |
| REST API | ⚡⚡ | ✅ | ✅ | ✅ | Free tier |
| Manual + tools | ⚡ | ✅ | ✅ | ✅ | Free |
Common mistakes
1. Converting full <html> documents without extracting body. You get YAML-like noise from <meta> tags.
2. Expecting perfect Notion/Confluence fidelity. Plan a human review pass.
3. Skipping link audit after migration. Broken relative links are the #1 post-migration bug.
4. Committing HTML entities. & in URLs — decode with typography pass.
5. No frontmatter on migrated posts. SSG builds need title, date, slug.
6. Double conversion. HTML → MD → HTML → MD accumulates artifacts — convert once, store Markdown as source of truth.
Reverse direction
Need Markdown → HTML again? See the Markdown to HTML guide and render API. Round-trip is lossy for layout — always keep Markdown as canonical.
Related articles
- Markdown to HTML guide — forward conversion
- Markdown vs HTML — format tradeoffs
- Notion Markdown guide — export quirks
- Docs-as-code guide — commit migrated files
- VS Code Markdown guide — edit and lint after import
Try it now
- Paste HTML: HTML to Markdown converter
- Preview result: Markdown editor
- Automate: API signup → convert endpoint docs
HTML to Markdown is the bridge back to portable text. Convert once, clean with tools, commit to Git — your content survives the next platform migration.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
Convert Markdown to clean HTML for CMS, email, and static sites — browser tools, CLI, JavaScript libraries, static generators, and API pipelines compared with code examples.
A hands-on tutorial for converting between Markdown, HTML, and PDF — clean sanitized HTML for any CMS, watermark-free PDFs, and HTML-to-Markdown for rescuing rich text. With a CI-ready API.
Markdown vs HTML — how they differ, which is faster to write, which works where, and a practical decision framework for picking the right tool every time.