HTML to Markdown

What is HTML to Markdown Conversion?

HTML to Markdown conversion transforms HTML markup into Markdown, a lightweight plain-text formatting syntax created by John Gruber in 2004. Markdown was designed to be readable without rendering. Where HTML requires opening and closing tags like <strong> and <a href="">, Markdown uses shorthand characters: **bold**, [links](url), and # headings. Converting HTML to Markdown produces files that are easier to read, edit, and version-control than raw HTML.

The conversion process maps HTML elements to their Markdown equivalents. A <h2> becomes ##, a <ul><li> becomes - item, and an <a> tag becomes [text](url). Some HTML elements have no direct Markdown equivalent, such as <div>, <span>, or custom data attributes. Converters typically strip these tags or pass them through as raw HTML, depending on configuration.

Markdown has become the standard writing format for developer documentation (GitHub, GitLab, Bitbucket), static site generators (Hugo, Jekyll, Astro), note-taking apps (Obsidian, Notion), and technical blogs. Converting existing HTML content to Markdown is a common step when migrating websites, importing CMS content, or archiving web pages in a portable format. Unlike HTML, Markdown files produce clean diffs in version control, making code review of documentation changes practical.

Why Use an HTML to Markdown Converter?

Manually rewriting HTML as Markdown is slow and error-prone, especially for pages with nested lists, tables, or dozens of links. An automated converter handles the structural mapping instantly and consistently.

HTML to Markdown Use Cases

HTML to Markdown Element Reference

The table below shows how common HTML elements map to their Markdown equivalents. This mapping follows GitHub-Flavored Markdown (GFM) conventions, which extend the CommonMark spec with tables, strikethrough, and task lists. Elements not listed here (such as <div>, <form>, or custom web components) have no Markdown equivalent and are either stripped or passed through as raw HTML.

Markdown Flavors: GFM vs CommonMark vs Original

Not all Markdown is the same. The output format matters because different platforms parse Markdown differently. The three most common flavors are GitHub-Flavored Markdown (GFM), CommonMark, and Gruber's original Markdown.

Code Examples

Working examples in JavaScript (Turndown), Python (markdownify and html2text), Go, and Pandoc on the command line.

import TurndownService from 'turndown'

const turndown = new TurndownService({ headingStyle: 'atx' })
const html = '<h1>Title</h1><p>A <strong>bold</strong> paragraph.</p>'
const md = turndown.turndown(html)
console.log(md)
// → "# Title\n\nA **bold** paragraph."

from markdownify import markdownify

html = '<h2>Section</h2><ul><li>First</li><li>Second</li></ul>'
md = markdownify(html, heading_style='ATX')
print(md)
# → "## Section\n\n- First\n- Second"

import html2text

converter = html2text.HTML2Text()
converter.body_width = 0  # disable line wrapping

html = '<p>Visit <a href="https://example.com">Example</a> for details.</p>'
md = converter.handle(html)
print(md)
# → "Visit [Example](https://example.com) for details."

package main

import (
	"fmt"
	md "github.com/JohannesKaufmann/html-to-markdown"
)

func main() {
	converter := md.NewConverter("", true, nil)
	html := `<h3>Go Example</h3><p>Code: <code>fmt.Println()</code></p>`
	markdown, _ := converter.ConvertString(html)
	fmt.Println(markdown)
	// → "### Go Example\n\nCode: `fmt.Println()`"
}

# Convert an HTML file to Markdown
pandoc input.html -f html -t markdown -o output.md

# Pipe HTML from stdin
echo '<p>Hello <em>world</em></p>' | pandoc -f html -t markdown
# → Hello *world*

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

Frequently Asked Questions