Skip to content

HTML to Markdown: Convert Web Content to Clean Markdown

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 TagMarkdown 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">![text](url)
<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

  1. Parse the HTML into a DOM tree using the browser's built-in parser
  2. Walk each node in document order (top to bottom, left to right)
  3. Check the node type — element, text, comment
  4. Map elements to Markdown syntax using the table above
  5. Handle nesting — a bold word inside a list item: - **bold item**
  6. Collapse whitespace — HTML's whitespace rules differ from Markdown's
  7. 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 ![Description](photo.jpg).

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

LanguageLibraryNotes
JavaScriptTurndownWidely used JS library. Extensible with plugins.
JavaScripthtml-to-mdLightweight alternative focused on simplicity.
PythonmarkdownifyConverts BeautifulSoup HTML trees to Markdown.
Pythonhtml2textAaron Swartz's original library. Handles most HTML correctly.
PHPleague/html-to-markdownPart of the PHP League ecosystem.
Rubyreverse_markdownConverts HTML to GitHub-Flavored Markdown.
Gohtml-to-markdownFast, handles tables and code blocks well.
Browser-basedWritePadPro HTML to MarkdownInstant 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.

Frequently Asked Questions

What HTML elements cannot be converted to Markdown?

Several HTML elements have no Markdown equivalent: forms and input fields, iframes and embedded widgets, custom components and web components, tables with merged cells (colspan/rowspan), details/summary elements, and any element that relies on CSS classes or inline styles for meaning. These elements are either stripped (losing the content), preserved as raw HTML within the Markdown (most converters support this), or converted to the closest approximation (an iframe becomes a link to the embedded URL). WritePadPro's converter handles the most common HTML patterns. It removes scripts, styles, forms and iframes, keeps the text of other unsupported elements without their tags (sub and sup stay as HTML), and turns tables with merged cells into a simple pipe table, so check those by hand.

Does converting HTML to Markdown lose any information?

Yes — some information is inevitably lost. CSS classes and styles are discarded (Markdown has no styling). Image dimensions specified in HTML attributes are lost. Table cell alignment may not transfer perfectly. Form elements are removed. JavaScript interactions are removed. Link targets (_blank) are not preserved in standard Markdown. However, all textual content, document structure (headings, lists, paragraphs), links (URLs and anchor text), images (source and alt text), and code blocks are preserved. For most content migration scenarios, the preserved information is what matters.

How do I convert an entire website to Markdown?

For a full website migration, you need a batch conversion pipeline: (1) Export or scrape the HTML content from each page. (2) Extract the main content area (remove navigation, headers, footers, sidebars). (3) Convert the content HTML to Markdown using a library like Turndown (JavaScript), markdownify (Python), or league/html-to-markdown (PHP). (4) Save each converted page as a .md file with appropriate frontmatter (title, date, category). (5) Post-process the Markdown files to fix formatting issues and update internal links. For individual pages, WritePadPro's browser-based converter handles the conversion instantly.

Should I use reference-style or inline links in the Markdown output?

For most use cases, inline links are preferred: [text](url). They keep the URL visible at the point of use, making the Markdown easier to read and edit. Reference-style links ([text][1] with [1]: url at the bottom) are better for documents with many links to the same URL (define once, reference multiple times) or very long URLs that would break the flow of the text. Most HTML-to-Markdown converters default to inline links. WritePadPro's converter produces inline links for maximum readability and portability.

Try These Tools

Related Articles