Convert HTML to Markdown: Complete Guide

Why Convert HTML to Markdown?

HTML and Markdown both represent formatted text, but they serve different purposes. HTML is designed for browsers — it is verbose, uses opening and closing tags, and supports complex layouts. Markdown is designed for humans — it is concise, readable as plain text, and focuses on content structure over presentation.

Common reasons to convert HTML to Markdown include: migrating blog content from a CMS (WordPress, Drupal) to a static site generator (Hugo, Jekyll, Gatsby) that uses Markdown files. Preparing documentation from web sources for inclusion in README files and wikis. Converting email newsletters or web content into a format that works in Markdown-based note-taking apps (Obsidian, Notion, Bear). Cleaning up rich text pasted from web pages into a simpler, more portable format.

The conversion is not always lossless. Markdown supports a subset of what HTML can express. Complex layouts, custom styling, embedded media, and interactive elements do not have Markdown equivalents. The conversion process must decide how to handle these elements — skip them, approximate them, or preserve them as raw HTML within the Markdown output.

HTML to Markdown Element Mapping

Here is how common HTML elements translate to Markdown syntax:

Headings: <h1> through <h6> become # through ######. The number of hash marks matches the heading level.

Paragraphs: <p> tags become plain text separated by blank lines. The tags themselves are removed.

Bold and italic: <strong> and <b> become **text**. <em> and <i> become *text*. Bold italic uses ***text***.

Links: <a href="url">text</a> becomes [text](url). Links with title attributes become [text](url "title").

Images: <img src="url" alt="text"> becomes ![text](url). The alt attribute becomes the Markdown image description.

Lists: <ul> with <li> items become lines prefixed with - or *. <ol> items become lines prefixed with 1., 2., etc. Nested lists are indented with spaces.

Code: Inline <code> becomes backtick-wrapped text. <pre><code> blocks become fenced code blocks with triple backticks. Language classes on the code element are preserved as the info string after the opening fence.

Blockquotes: <blockquote> becomes lines prefixed with >.

Horizontal rules: <hr> becomes --- or ***.

Tables: HTML tables convert to Markdown pipe tables. This works for simple tables but Markdown tables do not support merged cells (colspan/rowspan), cell alignment beyond basic left/center/right, or nested elements within cells.

Handling Edge Cases

Real-world HTML rarely maps cleanly to Markdown. Here are common challenges:

Nested inline formatting: HTML like <strong><em>text</em></strong> should become ***text***. Most converters handle simple nesting, but deeply nested or overlapping formatting can produce incorrect output.

Divs and spans: These generic containers have no Markdown equivalent. A converter must either strip them (losing any semantic meaning) or preserve them as raw HTML. If a div has a class that indicates a callout or warning, that information is lost in Markdown unless the converter has special handling.

Inline styles: Markdown does not support inline styling. Text colored with style="color: red" loses its color in conversion. There is no way to represent this in standard Markdown.

Empty elements: Empty paragraphs, empty links, and empty spans should be removed during conversion rather than producing empty Markdown syntax.

Line breaks: The <br> element is tricky. In Markdown, a line break within a paragraph requires either two trailing spaces or a backslash at the end of the line. Both are invisible and easy to lose when editing. Some converters use the explicit <br> tag in Markdown (which is valid — Markdown allows inline HTML).

Improving Conversion Quality

The quality of HTML-to-Markdown conversion depends on the source HTML quality. Clean, semantic HTML converts well. Messy, presentation-focused HTML converts poorly. Before converting, consider cleaning the HTML:

• Remove unnecessary wrappers. Strip <div> and <span> elements that serve only as styling hooks.
• Normalize formatting tags. Convert <b> to <strong> and <i> to <em> for consistency.
• Remove inline styles. Since Markdown cannot represent them, removing them before conversion produces cleaner output.
• Fix nesting errors. Improperly nested elements produce unpredictable conversion results.

After conversion, review the Markdown output. Check that headings have the correct level, links point to the right URLs, code blocks are properly fenced, and lists are correctly nested. A quick manual review catches issues that automated conversion misses.

Markdown Flavors

Different platforms support different Markdown extensions. When converting, know your target:

• CommonMark: The standardized core Markdown specification. Supports headings, paragraphs, emphasis, links, images, code, blockquotes, lists, and horizontal rules.
• GitHub Flavored Markdown (GFM): Adds tables, task lists, strikethrough, auto-linking, and fenced code blocks with syntax highlighting.
• Obsidian/Wiki-style: Adds wiki links ([[Page Name]]), callouts, and embedded content.

Convert HTML to Markdown Online

Our HTML to Markdown converter handles the conversion automatically. Paste your HTML and get clean Markdown output. The tool maps all standard elements, handles nested formatting, preserves code blocks with language hints, and converts tables to pipe syntax.

For elements that have no Markdown equivalent, you can choose to strip them entirely or preserve them as inline HTML. The converter produces GitHub Flavored Markdown by default, which is compatible with most platforms.