Skip to content
All posts
7 min read
markdown
html
convert
migration
guide

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?

MotivationBenefit
Docs-as-code.md files in Git with clean PR diffs
CMS migrationLeave WordPress/Webflow → static site
Knowledge base cleanupNotion/Confluence → Obsidian or repo
AI pipeline hygieneModels often return HTML despite prompts
Email / newsletter archiveHTML newsletters → searchable text
Scraping & researchWeb 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 patternProblemManual fix
Nested <div> layoutNo Markdown equivalentStrip wrappers
<span style="...">Inline CSS lostAccept loss or use HTML in MDX
Complex colspan tablesGFM has no colspanSimplify table or use HTML in MDX
<iframe> embedsBecomes link or dropsReplace with ![alt](thumbnail) + link
Custom web componentsUnknown tagsRemove or replace with text
&nbsp; spacingOdd whitespaceRun formatter

Set expectations: conversion is 80% automated, 20% editorial.

Method 1: Browser converter (fastest)

For one page or paste buffer:

  1. Open HTML to Markdown.
  2. Paste HTML source (View Source, DevTools copy, or export file).
  3. 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:

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

  1. Export XML or use a static crawl of rendered pages.
  2. Extract <article> or .entry-content HTML per post.
  3. Convert each to .md with frontmatter:
---
title: "Post title"
date: 2024-03-15
slug: post-title
---
  1. Map wp-content/uploads/ images to static/images/ and fix paths.

Notion

Notion Export → Markdown is the first step, but exports are messy. For HTML clipboard content:

  1. Paste into HTML to Markdown.
  2. Replace Notion callout remnants with callout syntax.
  3. 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:

  1. Simplify — one header row, one data row per concept.
  2. Split — one wide table → multiple narrow tables.
  3. Keep HTML — in MDX/Docusaurus, leave <table> inline.
  4. 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:

![Dashboard](https://cdn.example.com/photo.jpg)

Migration checklist for images:

  • Download hotlinked images to repo static/ folder
  • Update relative paths: ![](/images/photo.jpg)
  • Add alt text where HTML had empty alt=""
  • Run image inventory via API on the converted corpus

Comparison table

MethodSpeedGFM tablesBatchSanitizes HTMLCost
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. &amp; 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.

Try it now

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.