Why You'd Want HTML in Markdown Form

The demand for HTML-to-Markdown conversion has grown alongside the rise of static site generators and documentation platforms. Hugo, Jekyll, Gatsby, and Docusaurus all use Markdown as their primary content format. Notion, Obsidian, and Bear import Markdown natively.

If your content lives in a CMS that outputs HTML, you need a conversion step to move it. Doing this manually — tag by tag — for dozens of posts is not a realistic option. A converter handles the mechanical work so you can focus on reviewing and cleaning up the output.

The other use case is writing workflow optimization. Some editors work better in Markdown but receive content from non-technical contributors who use rich text editors that export HTML. Converting that HTML to Markdown keeps everything in a consistent format for version control.

The Mapping You Need to Know

HTML to Markdown conversion is essentially a tag substitution problem. Most common HTML elements have a direct Markdown equivalent. Here's what the mapping looks like for the tags you'll encounter most:

• <h1> through <h6> → # through ######
• <strong> and <b> → **bold**
• <em> and <i> → *italic*
• <a href="url">text</a> → [text](url)
• <img src="url" alt="desc"> → ![desc](url)
• <ul><li> → - item
• <ol><li> → 1. item
• <pre><code> → triple backtick code block
• <blockquote> → > quoted text

The tricky ones are tables and nested lists. Most basic converters handle tables by generating pipe-separated Markdown tables. Deeply nested lists can sometimes lose their nesting in conversion, so always review the output for those.

What Gets Lost in Translation

HTML to Markdown conversion isn't perfect. Some HTML features simply don't have Markdown equivalents, and knowing what those are will save you from frustrating debugging sessions.

CSS classes and inline styles are dropped entirely. If your HTML uses class="highlight" or style="color:red", that styling information disappears. Markdown doesn't support custom styling.

Complex tables with merged cells (colspan, rowspan) can't be represented in Markdown's simple pipe table syntax. These will usually convert to a simplified version that loses the cell merging.

Custom HTML elements and framework-specific tags like Angular or React components are stripped, leaving only their text content. If your HTML uses web components, those become plain text in Markdown.

The practical takeaway: always review your converted Markdown before publishing. Use the output as a starting point, not a finished product.

Real Migration Scenarios

Tips for Cleaner Conversion Results

The cleaner your input HTML, the cleaner your Markdown output will be. Before converting, remove wrapper divs, navigation elements, headers, footers, and sidebar HTML that you don't want in your Markdown content.

Extract just the content portion — the <article> or main content <div> — rather than pasting the entire page source. This avoids cluttering your Markdown with menu items and footer links.

After conversion, do a quick pass to check headings hierarchy (h1 → h2 → h3 progression), verify all links still work, and confirm code blocks are properly fenced. Most converters handle the basics well, but edge cases in the original HTML can sometimes produce unexpected output.

HTML to Markdown Across Languages