Why Convert HTML to Markdown?
HTML is the language of the web, but it is not the language of writing. HTML tags clutter content with structural markup that makes text harder to read, edit, and maintain. Markdown strips away that complexity, producing clean, readable source text that is easy to version-control, portable across platforms, and focused entirely on content.
Convert any HTML to Markdown with WritePadPro's HTML to Markdown Converter — paste HTML source code and get clean Markdown syntax instantly.
The need for HTML-to-Markdown conversion arises whenever content needs to move from an HTML-centric system to a Markdown-centric one — or when a writer wants the readability benefits of Markdown for content originally created in HTML. For the reverse conversion, see our Markdown to HTML Guide.
Common Use Cases
CMS Migration
Moving content between content management systems is a common reason for HTML-to-Markdown conversion. WordPress stores posts as HTML. Migrating to a static site generator (Jekyll, Hugo, Gatsby) or a platform that imports Markdown (such as Ghost or Notion) requires converting that HTML to Markdown. A 500-post WordPress blog migration means converting 500 HTML articles to Markdown files.
The conversion must handle WordPress-specific HTML patterns: shortcodes, custom classes, embedded media, and plugin-generated markup. Clean conversion produces Markdown files that build correctly in the new system without manual editing.
Content Archiving
Markdown is one of the most portable content formats. It is plain text that should stay readable for decades without special software. Archiving web content as Markdown — rather than as HTML with dependencies on CSS, JavaScript, and external resources — creates a permanent, lightweight record. A 10 MB HTML page with images and scripts might produce a 50 KB Markdown file that contains all the textual content.
Version Control for Content
Git tracks changes in text files. HTML diffs are noisy — tag changes, attribute modifications, and whitespace differences obscure the actual content changes. Markdown diffs are clean — you see exactly what words changed, what was added, and what was removed. Content teams that use Git for collaboration convert HTML content to Markdown for cleaner version history.
Documentation Consolidation
Technical documentation often exists in multiple formats: wiki pages (HTML), knowledge base articles (HTML), internal docs (Google Docs/HTML export). Converting everything to Markdown creates a unified format that works with documentation tools like MkDocs, Docusaurus, and GitBook. For a complete Markdown syntax reference, see our Markdown Complete Guide.
Email Content Extraction
HTML emails contain extensive table-based layout markup. Converting email content to Markdown extracts the readable text in a clean format, discarding the layout tables, inline styles, and tracking pixels. The resulting Markdown is easier to quote, forward, and archive.
How HTML-to-Markdown Conversion Works
The conversion process walks the HTML document tree (DOM) and maps each HTML element to its Markdown equivalent.
The Tag-to-Syntax Mapping
| HTML Tag | Markdown Output |
|---|---|
<h1>...</h1> | # ... |
<h2>...</h2> | ## ... |
<h3>...</h3> | ### ... |
<strong>...</strong> or <b> | **...** |
<em>...</em> or <i> | *...* |
<a href="url">text</a> | [text](url) |
<img src="url" alt="text"> |  |
<ul><li>...</li></ul> | - ... |
<ol><li>...</li></ol> | 1. ... |
<blockquote>...</blockquote> | > ... |
<code>...</code> | `...` |
<pre><code>...</code></pre> | Fenced code block (```) |
<hr> | --- |
<br> | Two trailing spaces or \ |
<p>...</p> | Text with blank line before/after |
The DOM Walking Process
- Parse the HTML into a DOM tree using the browser's built-in parser
- Walk each node in document order (top to bottom, left to right)
- Check the node type — element, text, comment
- Map elements to Markdown syntax using the table above
- Handle nesting — a bold word inside a list item:
- **bold item** - Collapse whitespace — HTML's whitespace rules differ from Markdown's
- Output clean Markdown with proper spacing between elements
Handling Complex HTML
Simple HTML converts cleanly to Markdown. Complex HTML requires decisions about what to preserve and what to discard.
Tables
HTML tables with <table>, <thead>, <tbody>, <tr>, <th>, <td> map directly to Markdown pipe tables — but only if the table is simple (no merged cells, no nested tables, no rowspan/colspan). Complex tables with merged cells have no Markdown equivalent and must either be simplified or passed through as raw HTML.
CSS Classes and Styles
Markdown has no concept of CSS classes or inline styles. <div class="alert alert-warning">Warning text</div> becomes just "Warning text" in Markdown. Visual styling information is lost. If the styling carries semantic meaning (warning, info, error), some converters preserve it as an HTML block within the Markdown.
Embedded Media
Videos, iframes, and interactive widgets have no Markdown equivalent. <iframe src="youtube.com/..."> must either be preserved as raw HTML in the Markdown or replaced with a link: [Watch video](youtube.com/...). WritePadPro's converter removes iframes, so add a link by hand if you need one. Images convert cleanly: <img src="photo.jpg" alt="Description"> becomes .
Nested Lists
Deeply nested HTML lists (3+ levels) sometimes lose proper indentation during conversion. The converter must track nesting depth and apply correct Markdown indentation (2 or 4 spaces per level). Verify nested list structure in the output after converting complex lists. For stripping HTML entirely rather than converting, see the Strip HTML Tags tool.
Cleaning Up the Output
Raw HTML-to-Markdown conversion often produces output that needs post-processing. WritePadPro's converter already collapses extra blank lines and trims trailing spaces, but the checks below are still worth a look.
Extra Blank Lines
HTML block elements (divs, sections, articles) that were on separate lines leave behind extra blank lines when converted. Collapse runs of 3+ blank lines to single blank lines: replace \n{3,} with \n\n.
Residual HTML
Elements with no Markdown equivalent (forms, scripts, custom components) may remain as raw HTML in the output. Review and remove any residual HTML that is not needed in the Markdown version.
Link Formatting
Some converters produce reference-style links by default, which can clutter the bottom of the document with link definitions. Convert to inline links if you prefer: change [text][1] with [1]: url at the bottom to [text](url) inline.
Whitespace Normalization
HTML collapses all whitespace to single spaces when rendering, but the source may contain tabs, multiple spaces, and irregular indentation. After conversion, run the output through whitespace normalization to ensure clean Markdown formatting. For related cleanup, see our Rich Text to Markdown Guide.
HTML-to-Markdown Libraries
| Language | Library | Notes |
|---|---|---|
| JavaScript | Turndown | Widely used JS library. Extensible with plugins. |
| JavaScript | html-to-md | Lightweight alternative focused on simplicity. |
| Python | markdownify | Converts BeautifulSoup HTML trees to Markdown. |
| Python | html2text | Aaron Swartz's original library. Handles most HTML correctly. |
| PHP | league/html-to-markdown | Part of the PHP League ecosystem. |
| Ruby | reverse_markdown | Converts HTML to GitHub-Flavored Markdown. |
| Go | html-to-markdown | Fast, handles tables and code blocks well. |
| Browser-based | WritePadPro HTML to Markdown | Instant conversion with no installation, runs locally. |
Using WritePadPro's HTML to Markdown Converter
WritePadPro's HTML to Markdown Converter transforms HTML into clean Markdown instantly.
Step 1: Open the Tool
Navigate to the HTML to Markdown Converter. You will see an input area for HTML and, below it, an output area with a Markdown tab and a Preview tab.
Step 2: Paste HTML
Paste your HTML source code — from web page source, CMS export, email source, or any HTML content. The tool accepts any valid HTML.
Step 3: View the Markdown
The converter walks the HTML DOM tree and maps each element to Markdown syntax. The Markdown tab shows the result, with heading levels, list indentation, inline links, and fenced code blocks (the language is kept when the code element has a language-xxx class). The Preview tab renders the Markdown so you can check it, and a stats line compares the size of the HTML and the Markdown. Script, style, form and iframe elements are removed.
Step 4: Copy and Use
Click Copy Markdown or Download .md, then use the Markdown in:
- Static site generators (Jekyll, Hugo, Gatsby, Eleventy)
- Platforms that import Markdown (Ghost, Notion)
- Git repositories (README files, documentation)
- Note-taking apps (Obsidian, Bear, Joplin)
- Any Markdown-supporting platform
Privacy
All conversion runs locally in your browser using DOM parsing. Your HTML content is never transmitted to any server.
Summary
HTML-to-Markdown conversion extracts content from HTML markup and expresses it in clean, readable Markdown syntax. The process walks the HTML DOM tree and maps each element to its Markdown equivalent — headings to #, bold to **, links to [text](url), lists to - and 1., code to backticks.
Common use cases include CMS migration, content archiving, version control, documentation consolidation, and email content extraction. Complex HTML elements like styled divs, merged table cells, and embedded media require special handling since Markdown has no direct equivalents.
Convert HTML to Markdown with WritePadPro's HTML to Markdown Converter — DOM-based conversion running entirely in your browser. For the complete Markdown syntax, see our Markdown Complete Guide.