HTML to Markdown Converter Guide: Migrate Content and Write Cleaner Docs

Markdown has become the preferred writing format for developers, technical writers, and content creators. It is readable as plain text, renders beautifully on GitHub, documentation platforms, and most modern CMSs, and is far cleaner to write and maintain than raw HTML. If you have content trapped in HTML format, converting it to Markdown opens up a world of portability and easier editing.

This guide explains why you might convert HTML to Markdown, shows the conversion mappings for common elements, walks through a real example, and covers the elements that do not convert cleanly.

Why Convert HTML to Markdown?

There are several common situations where HTML-to-Markdown conversion is genuinely useful:

• Blog or CMS migration — moving from a platform that stores content as HTML (like WordPress) to one that uses Markdown (like Ghost, Gatsby, Hugo, or Eleventy)
• Creating GitHub README files — converting an existing HTML documentation page into a README.md for a repository
• Documentation portals — migrating legacy HTML documentation into a docs-as-code system like MkDocs, Docusaurus, or VuePress
• Email or web content repurposing — taking HTML scraped from the web and converting it to clean Markdown for editing and republication
• Writing tools and editors — many writing tools import Markdown but not HTML, so conversion enables cross-platform content portability

HTML Elements and Their Markdown Equivalents

A Worked Conversion Example

Here is a typical blog post excerpt in HTML:

<h2>Getting Started with Docker</h2>
<p>Docker makes it easy to package applications into <strong>containers</strong>
that run consistently across any environment.</p>
<p>Install Docker using the following command:</p>
<pre><code>sudo apt-get install docker-ce</code></pre>
<ul>
  <li>Works on Linux, macOS, and Windows</li>
  <li>Isolates dependencies from the host system</li>
  <li>Enables consistent <em>dev/prod parity</em></li>
</ul>
<p>Read the <a href="https://docs.docker.com">official docs</a> for more.</p>

After conversion to Markdown:

## Getting Started with Docker

Docker makes it easy to package applications into **containers**
that run consistently across any environment.

Install Docker using the following command:

```
sudo apt-get install docker-ce
```

- Works on Linux, macOS, and Windows
- Isolates dependencies from the host system
- Enables consistent *dev/prod parity*

Read the [official docs](https://docs.docker.com) for more.

The Markdown version is noticeably cleaner and easier to read and edit in a plain text editor.

Elements That Don't Convert Cleanly

Not all HTML has a Markdown equivalent. Here is what to expect with complex markup:

Complex Tables

Basic HTML tables convert reasonably well to Markdown's pipe table syntax. However, tables with merged cells (colspan, rowspan), nested tables, or complex formatting have no clean Markdown equivalent. The converter will produce a best-effort flat table, but merged cells will be lost.

Custom Classes and Inline Styles

Markdown has no concept of CSS classes or inline styles. A <p class="warning"> will convert to a plain paragraph. If your content depends on CSS classes for its appearance or meaning, that semantic information cannot be represented in standard Markdown. You will need to manually add notes or use a Markdown extension.

Nested Lists with Mixed Types

A numbered list that contains bullet sub-lists (or vice versa) can be tricky. Most converters handle simple nesting correctly, but deep or complex mixed-type nesting sometimes produces incorrect indentation in the output. Always review converted nested lists carefully.

Forms, Iframes, and Interactive Elements

HTML elements like <form>, <input>, <iframe>, <video>, and <canvas> have no Markdown equivalent. Converters either drop these entirely or fall back to preserving the raw HTML inline (which some Markdown renderers support via passthrough HTML).

What to Do with Non-Convertible Elements

Most Markdown renderers — including GitHub Flavored Markdown and most static site generators — support inline HTML. This means you can include raw HTML tags directly in your Markdown file and they will be rendered correctly. For elements with no Markdown equivalent, leaving them as HTML in the Markdown file is often the best solution:

This is regular Markdown text.

<figure>
  <img src="chart.png" alt="Q1 Results">
  <figcaption>Figure 1: Q1 Revenue</figcaption>
</figure>

More regular Markdown text here.

Tools and Libraries for HTML-to-Markdown Conversion

Pandoc

Pandoc is a universal document converter that runs from the command line. It handles HTML to Markdown conversion extremely well, including tables and footnotes. It is the gold standard for bulk document conversion:

pandoc -f html -t markdown input.html -o output.md

Turndown.js

Turndown is a JavaScript library specifically designed for HTML-to-Markdown conversion in the browser or Node.js. It is highly configurable — you can define custom rules for any HTML element. Many online conversion tools use Turndown under the hood.

html2text (Python)

The html2text Python library converts HTML to Markdown-formatted text. It is commonly used in scripts that process web content or scraped pages.

Use Cases in Practice

Migrating WordPress to Ghost or a Static Site Generator

WordPress stores post content as HTML in a MySQL database. When migrating to Ghost (which uses Markdown or its Mobiledoc format) or to a static site generator like Hugo or Eleventy, you need to bulk-convert hundreds or thousands of HTML posts to Markdown. A script using Pandoc or Turndown with the WordPress export XML is the standard approach.

Creating Documentation from Web Content

Technical writers often gather reference material from product web pages and need to incorporate it into a docs-as-code system. Converting the HTML to Markdown provides a starting point that can then be edited and integrated into the docs workflow.

GitHub README Files

If you have an existing HTML page describing a project (perhaps from an old project website) and want to create a README.md from it, the converter produces clean Markdown that you can refine and commit to your repository.

Summary

Converting HTML to Markdown makes content more portable, easier to edit, and compatible with modern developer tools and documentation platforms. Most standard HTML elements — headings, paragraphs, bold, italic, links, images, lists, and code — convert cleanly. Complex tables, custom classes, forms, and interactive elements do not have Markdown equivalents and need to be handled manually. For one-off conversions, the tool above works instantly. For bulk migration, Pandoc or a scripted Turndown.js pipeline is the right approach.