HTML to Markdown: The Complete Conversion Guide

The Mapping Between HTML and 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="x" alt="y">     →  ![y](x)
<code>inline</code>        →  backtick-inline-backtick
<pre><code>block</code></pre>  →  fenced code block
<ul><li>item</li></ul>   →  - item
<ol><li>item</li></ol>   →  1. item
<blockquote>text</blockquote> → > text
<hr>                        →  ---
<br>                        →  two spaces at end of line (or backslash)

HTML to Markdown in JavaScript

// Turndown — the most popular library
import TurndownService from "turndown";

const td = new TurndownService({
  headingStyle: "atx",     // # style (vs setext underline)
  codeBlockStyle: "fenced", // triple backtick (vs indent)
  bulletListMarker: "-",
});

const markdown = td.turndown(htmlString);

// Custom rule example: convert <mark> to ==highlight==
td.addRule("mark", {
  filter: "mark",
  replacement: (content) => `==${content}==`,
});

Markdown to HTML

// marked — fast, CommonMark compliant
import { marked } from "marked";
const html = marked.parse("# Hello\n\nThis is **Markdown**.");

// remark — AST-based, composable
import { remark } from "remark";
import remarkHtml from "remark-html";
const result = await remark().use(remarkHtml).process(markdownString);
const html = String(result);

Elements Without Markdown Equivalents

Not everything in HTML maps to Markdown:

• <table> — GFM has table syntax; CommonMark does not
• <div>, <span> — no equivalent; use raw HTML in Markdown (most parsers allow it)
• <figure>, <figcaption> — use raw HTML
• <video>, <audio> — embed as raw HTML
• Inline styles — no Markdown equivalent

Most Markdown parsers allow raw HTML passthrough for these cases:

Regular Markdown paragraph.

<div class="custom">
  This raw HTML is preserved.
</div>

Back to Markdown.

CMS Migration Workflow

When migrating from a CMS that stores HTML to one that uses Markdown:

1. Export all HTML content
2. Run Turndown with custom rules for your HTML patterns
3. Review output for unsupported elements
4. Handle tables, embeds, and custom components manually or with additional rules
5. Validate the round-trip: Markdown → HTML should produce equivalent rendered output

Convert HTML ↔ Markdown Instantly

Use ToolsVito's HTML ↔ Markdown Converter to convert in either direction in your browser — no library setup needed.