How to Convert HTML to Markdown

March 22, 2026 · 7 min read

Markdown is the lingua franca of developer documentation, README files, and static site generators. But content often starts as HTML — copied from web pages, exported from CMSes, or generated by WYSIWYG editors. Converting HTML to Markdown gives you clean, portable, version-control-friendly text.

This guide covers the conversion mapping, the best tools for the job, and common pitfalls to watch for.

HTML to Markdown Syntax Mapping

Every HTML element has a Markdown equivalent (or close approximation):

HTML	Markdown
<h1>Title</h1>	# Title
<h2>Section</h2>	## Section
<strong>bold</strong>	bold
<em>italic</em>	italic
<a href="url">text</a>	[text](url)
<img src="url" alt="alt">	![alt](url)
<code>inline</code>	`inline`
<pre><code>block</code></pre>	```block```
<ul><li>item</li></ul>	- item
<ol><li>item</li></ol>	1. item
<blockquote>text</blockquote>	> text
<hr>	---

Elements with no Markdown equivalent (like <div>, <span>, or <table> with complex formatting) are either kept as raw HTML or stripped during conversion, depending on the tool.

Convert HTML to Markdown instantly

Paste your HTML and get clean Markdown output — free, no signup, runs in your browser.

Open HTML to Markdown Converter

Method 1: Online Converter (Quickest)

For one-off conversions, an online tool is the fastest option. Use the HTML to Markdown converter on UtilShed — paste HTML on the left, get Markdown on the right. Everything runs client-side, so nothing is sent to a server.

This is ideal when you're copying content from a web page, converting a single file, or just need to quickly see what the Markdown equivalent of some HTML looks like.

Method 2: Turndown (JavaScript)

Turndown is the most popular HTML-to-Markdown library for JavaScript. It's what most online converters (including ours) use under the hood.

In Node.js

npm install turndown

const TurndownService = require('turndown');
const turndown = new TurndownService();

const html = '<h1>Hello</h1><p>This is <strong>bold</strong> text.</p>';
const markdown = turndown.turndown(html);

console.log(markdown);
// # Hello
//
// This is **bold** text.

Custom Rules

Turndown lets you add custom rules for elements that don't have a standard Markdown mapping:

turndown.addRule('strikethrough', {
    filter: ['del', 's'],
    replacement: (content) => `~~${content}~~`
});

// <del>deleted</del> → ~~deleted~~

GFM (GitHub Flavored Markdown)

For tables, strikethrough, and task lists, use the GFM plugin:

npm install turndown-plugin-gfm

const { gfm } = require('turndown-plugin-gfm');
turndown.use(gfm);

// Now handles <table>, <del>, and <input type="checkbox">

Method 3: Pandoc (CLI)

Pandoc is the Swiss Army knife of document conversion. It handles HTML to Markdown (and dozens of other format pairs):

# Install (macOS)
brew install pandoc

# Install (Ubuntu/Debian)
sudo apt install pandoc

# Convert a file
pandoc input.html -f html -t markdown -o output.md

Pandoc supports multiple Markdown flavors:

# GitHub Flavored Markdown
pandoc input.html -f html -t gfm -o output.md

# CommonMark
pandoc input.html -f html -t commonmark -o output.md

# Pandoc's extended Markdown (default)
pandoc input.html -f html -t markdown -o output.md

Pandoc is the best choice for batch conversion (converting many files at once) or when you need precise control over the output format.

Method 4: Python

The markdownify library is the Python equivalent of Turndown:

pip install markdownify

from markdownify import markdownify as md

html = '<h1>Hello</h1><p>This is <strong>bold</strong> text.</p>'
result = md(html)

print(result)
# Hello
# =====
#
# This is **bold** text.

Common Conversion Pitfalls

Tables — Standard Markdown doesn't support tables. You need GFM (GitHub Flavored Markdown) or the table will be kept as raw HTML or stripped.
Nested lists — Indentation matters in Markdown. Some converters don't handle deeply nested <ul>/<ol> correctly.
Inline styles — Markdown has no concept of CSS. Elements like <span style="color:red"> lose their styling.
HTML entities — Characters like & and < should be decoded back to & and <.
Whitespace — HTML collapses whitespace; Markdown is whitespace-sensitive. Watch for extra blank lines or missing line breaks.
Images with dimensions — <img width="200"> can't be represented in standard Markdown. The dimensions are lost.

When to Convert HTML to Markdown

Migrating a CMS — moving from WordPress/Ghost to a static site generator (Hugo, Jekyll, Astro) that uses Markdown files
Documentation — converting internal docs from Confluence/Notion HTML exports to Markdown for Git repos
Content scraping — extracting article content from web pages into a clean, readable format
Email templates — starting with a rendered HTML email and creating a Markdown source version
Version control — Markdown diffs are far more readable than HTML diffs in pull requests

Try It Now

Use the HTML to Markdown converter on UtilShed for quick conversions. For batch processing or integration into a build pipeline, use Turndown (JS), markdownify (Python), or Pandoc (CLI).

Related tools:

HTML to Markdown Converter — convert HTML to Markdown online
Markdown to HTML Converter — go the other direction
Markdown Preview — preview Markdown rendered as HTML
HTML Beautifier — format and indent HTML for readability
HTML Entity Encoder — encode special characters for HTML