HTML to Markdown

Stop Copy-Pasting Broken Markup: When HTML to Markdown Actually Saves Your Day

There's a specific kind of frustration that hits when you're trying to move content from a webpage into a documentation file, a GitHub README, or a static site generator — and the pasted HTML turns your clean repo into a soup of <div> tags and inline styles. The HTML to Markdown converter solves exactly this, and it does it in a way that's genuinely less annoying than you'd expect.

This is one of those browser-based tools that works without ceremony. Paste your raw HTML on the left, get clean Markdown on the right. No account, no install, no plugin chain. But the interesting part isn't what it does in theory — it's how it handles real-world HTML, which is rarely clean.

What "Real-World HTML" Actually Looks Like (And Why It Matters)

Most conversion tutorials show you examples like this:

<h1>Hello World</h1><p>This is a paragraph.</p>

That's not what you're dealing with. You're dealing with stuff scraped from a CMS, or copied from a Notion export, or pulled from a WordPress page — which means nested <span> tags with color styles, <strong> inside <em> inside <p>, anchor tags with tracking parameters, image tags with srcset attributes, and the occasional <!-- --> comment that snuck in from a page template.

The HTML to Markdown tool strips presentational cruft while preserving structural meaning. A <strong> tag becomes **bold**. A nested list stays a nested list. An <a href> with a 40-character UTM-tagged URL becomes a clean Markdown link with the original display text intact. What gets discarded is everything that's purely cosmetic — style="" attributes, wrapper divs without semantic purpose, empty <span> elements.

The Image Handling Nuance Nobody Mentions

Since this tool falls under the image and photo category, let's talk about where it actually earns that label. When your HTML contains an <img> tag, the output is Markdown's image syntax: ![alt text](image-url). Simple enough. But the useful part is what it does with the alt attribute.

If your original HTML looks like this:

<img src="https://example.com/photos/sunset.jpg" alt="Golden hour over the mountains" title="Sunset photo from Manali trip" />

You get back:

![Golden hour over the mountains](https://example.com/photos/sunset.jpg "Sunset photo from Manali trip")

The title attribute is preserved in quotes after the URL — which is valid Markdown and actually useful if you're migrating a photo gallery page into something like Jekyll or Hugo where the title attribute shows as a tooltip. Most converters silently drop the title. This one keeps it.

Where it gets less clean is with responsive image markup — the <picture> element with multiple <source> tags. Those don't have a Markdown equivalent, so you'll get just the fallback <img> reference. That's the right call. There's no sense inventing custom syntax for something Markdown can't represent natively.

A Concrete Workflow: Migrating a Photo Blog to a Static Site

Here's how this plays out in practice. Say you're moving a photo blog from WordPress to a Hugo-based static site. You have 60-something posts, each with a mix of text, embedded images, and occasional blockquotes from caption text. Doing this by hand would take a day. Doing it post-by-post through a conversion tool still takes time, but it's measurably faster.

1. Export your WordPress posts (the built-in exporter gives you XML, but plugins like WP All Export can give you per-post HTML files).
2. Open the HTML for each post, copy the content section — not the full page, just the article body inside <article> or <div class="entry-content">.
3. Paste into the left pane of HTML to Markdown, get converted output on the right.
4. Copy the Markdown, drop it into a new Hugo content file, and add your front matter manually.

The conversion handles the heavy structural work — turning your <h2> headers into ##, your <blockquote> captions into > syntax, your photo links into proper Markdown image references. You spend your time on the post-level stuff (front matter, taxonomy, slugs) rather than manual markup translation.

Things to Watch Out For

No tool is perfect at this, and it's worth knowing where you'll need to do some cleanup.

• Tables from WordPress: HTML tables convert to Markdown pipe tables, which is correct — but only if the original table was well-formed. Tables built with <div> grids for layout purposes will come out as blank or garbled. Those aren't really tables; they're just divs dressed as tables.
• Inline code inside paragraphs: Works well when the original uses <code> tags. If someone styled something as code using <span class="code-style">, it gets treated as plain text because the semantic signal isn't there.
• Relative image paths: If your HTML uses src="/wp-content/uploads/2024/05/photo.jpg" without a domain, the Markdown output will also have a relative path. That's fine if you're staying on the same server; it breaks if you're migrating somewhere else. You'll want to either fix these before converting or do a find-replace on the output.
• Nested ordered lists with letters or Roman numerals: Standard Markdown doesn't support these. You'll get plain numbered lists instead. If your content relies on legal-document-style outline numbering, Markdown may not be your destination format anyway.

The Quick Spot-Check Before You Paste Anywhere

One habit worth developing: before you paste converted Markdown into your actual files, paste it into a Markdown previewer first. Even a quick paste into a GitHub comment box (using the Preview tab) shows you whether your headers rendered, your images linked correctly, and your lists didn't collapse into a single paragraph.

The most common issue is extra blank lines — or missing blank lines — around block elements. Markdown is picky about this. An image that's supposed to stand alone on its line needs a blank line before and after it to render as a block element rather than being inlined with the surrounding text. If your photo page looks wrong in the preview, that's usually why.

When to Use This vs. Pandoc

If you're a command-line person, you might wonder why to use a browser tool when pandoc -f html -t markdown exists. Fair question. Pandoc is more powerful and handles edge cases better, especially around footnotes, citations, and complex table structures. But Pandoc requires installation, familiarity with its flags, and some configuration to produce "clean" Markdown rather than its default which preserves a lot of HTML attributes as raw HTML passthrough.

The browser tool wins for quick, one-off conversions where you just need the content cleaned up and don't want to open a terminal. It also wins for non-technical collaborators — a designer or writer migrating their own content can use it without touching the command line at all.

For bulk automated migration, Pandoc via a shell script will beat any browser tool. For individual posts, article sections, or one-time content moves, the HTML to Markdown converter does the job without setup friction.

The Real Time Savings

What this tool is actually selling is editing time, not conversion time. The conversion itself takes two seconds. The value is that you start with something 85% correct instead of starting from scratch or from a mess of tags. That remaining 15% — fixing a relative image path here, adjusting a heading level there, checking that a photo caption didn't get swallowed — takes maybe three minutes per post instead of fifteen.

Multiply that across sixty blog posts and you've recovered an afternoon.