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. Learning how to convert HTML to Markdown properly is the difference between a weekend migration and a month of cleanup. This guide works through the HTML to Markdown tool, shows a real conversion, lists what gets lost in conversion 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 tool 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 of the HTML to Markdown tool and click Convert to Markdown. Turndown, the library underneath, walks the element tree and writes out ATX headings (hash marks rather than underlines), fenced code blocks, and hyphen bullets. The result appears in the Markdown pane, ready to copy into a file.

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. There are no options to configure, 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 gets lost in conversion

Knowing what gets lost in conversion 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.
Tables lose their pipes. The core converter outputs table content as plain text lines, so real tables need manual rebuilding or a raw-HTML island in the file.
Anchor ids go away, and with them the deep links other pages pointed at. Audit incoming links before retiring old URLs.
Iframes, embeds, and scripts don't translate. Videos and widgets need a shortcode or component in the new stack.

Migrating cms content to markdown, page by page

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. 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.
Trusting tables to survive. They flatten silently, and nobody notices until the pricing page reads like a run-on sentence.
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 Markdown to HTML 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.