Developer Tools·4 min read

How to Convert HTML to Markdown for a CMS Migration

Every CMS migration hits the same wall: years of content stored as HTML, and a new stack that wants Markdown files. Doing the conversion properly is the difference between a weekend migration and a month of cleanup. This guide works through the HTML to Markdown Converter, shows a real conversion, lists what the conversion keeps and what it drops so nothing surprises you mid-migration, and finishes with the checks worth running before you commit a few hundred converted posts to a repo.

Open the free HTML to Markdown Converter All insights

The migration behind most conversions

The scenario.

The pattern repeats everywhere: a decade of posts in WordPress or a homegrown CMS, and a new stack, Hugo, Astro, Docusaurus, a docs-as-code pipeline, that wants a folder of .md files. The database export gives you HTML bodies, and someone has to turn hundreds of them into Markdown that still reads correctly.

The same conversion shows up at smaller scale too: saving an article into your notes, moving a page to a wiki, or feeding readable text to an LLM without the tag soup. In every case the job is identical: keep the structure, drop the noise.

How to convert HTML to Markdown in two panes

Paste the markup into the HTML pane. With Live mode on, the default, the Markdown appears as you paste; Convert to Markdown runs it again on demand. Turndown, the library underneath, walks the element tree and writes out ATX headings (hash marks rather than underlines), fenced code blocks, and hyphen bullets. Bold becomes double asterisks and italic becomes underscores. The result appears in the Markdown pane with a Copy button, ready to paste into a file. Try sample loads a snippet with a table, a strikethrough and a script tag if you want to see all three handled at once.

Those output conventions are deliberate: they're the defaults GitHub and nearly every static site generator agree on, so converted files behave the same in your repo as hand-written ones. The defaults need no configuring, and any style options you do change apply to every page, which for a migration is a feature: every page converts under identical rules, so a fix you script for one post applies to all of them.

One block of markup, converted

Input: <h2>Pricing</h2><p>Plans start at <strong>$9</strong> a month.</p><ul><li>Free trial</li><li>Cancel anytime</li></ul>

Output, four short lines of Markdown: ## Pricing, then Plans start at **$9** a month., then - Free trial and - Cancel anytime. Every element found its shorthand: the h2 became hashes, the strong tag became double asterisks, the list became hyphens. Nothing about the visual container, no classes, wrappers, or spacing, came along, because Markdown has no place to put it.

Links and images behave just as predictably. An anchor tag becomes a [text](url) pair, and an img element becomes the ![alt](src) form, which is why preserving alt text in the source pays off twice: once for accessibility on the old site, and again as ready-made captions in the new one.

What survives, and what doesn't

Tables and page code are handled for you. A table becomes a GitHub-style pipe table, with its first row used as the header. Text inside del, s or strike tags becomes ~~strikethrough~~. Script, style and noscript blocks are dropped entirely, so tracking snippets and inline CSS never turn into stray text in your posts. Knowing the rest up front turns surprises into decisions you make on purpose:

Classes, ids, and inline styles vanish. Markdown carries structure, not presentation, so any meaning encoded in a class name disappears.
Table cells flatten to one line. Line breaks, paragraphs or lists inside a cell are joined with spaces, and merged cells are not rebuilt, so complex tables need a check by eye.
Anchor ids go away, and with them the deep links other pages pointed at. Audit incoming links before retiring old URLs.
Iframes and embeds don't translate. Videos and widgets need a shortcode or component in the new stack.

Migrating CMS content, one body at a time

A clean migration converts bodies, not pages. Extract just the article markup from each export, skipping the header, navigation, sidebar, and footer, and convert that. For a single live page, Convert web page with Main content only ticked does this trimming for you. You'll dodge the pile of junk links a full-page conversion produces.

Two more checks pay for themselves. Scan heading levels on a converted sample, since sloppy CMS markup often used h4 purely for its font size, and your new theme will expose that instantly. Then fix image paths in the same pass: relative URLs from the old domain break the moment files move, while alt text survives and is worth keeping.

Conversion mistakes that surface weeks later

These are the ones that don't show up in the demo but do show up in production. A converted post can look perfect in a quick skim and still carry all four.

Converting full page source, so navigation menus and cookie banners become content in every single post.
Assuming every table survived intact. Simple grids convert cleanly, but a pricing table with merged cells or lists inside cells needs a render check.
Retiring the old site before auditing anchor links, leaving deep links that now scroll nowhere.
Skipping a render check on nested lists, the single most fragile structure in CMS-generated markup.

Round trips and neighboring tools

Before committing hundreds of converted posts, round-trip a sample: run the new Markdown through the Markdown to HTML Converter and compare the render against the original page. Differences cluster exactly where conversions fail, so ten minutes of spot-checking catches most systemic problems.

When the source markup itself is broken, unclosed li elements are a CMS classic, clean it up with the HTML Beautifier first so the nesting is visible and fixable before you convert. And when you don't need Markdown at all, just plain readable text, Strip HTML Tags is the blunter, faster instrument.