🔄 HTML to Markdown

What HTML to Markdown Actually Does — And Where It Breaks

The premise sounds trivially simple: paste HTML, get Markdown. But anyone who has run a WordPress export through a converter and then tried to drop the result into a Hugo or Astro site knows how much can go wrong between angle brackets and hash signs. HTML to Markdown — the browser-based tool at htmlmarkdown.com — is built on Turndown, one of the most mature open-source conversion libraries available, and it gets a surprising number of edge cases right. Understanding where it succeeds and where it quietly fails is the difference between a five-minute content migration and a three-hour cleanup session.

Nine Settings That Actually Matter

Most people open the tool, paste their HTML, copy the output, and move on. That works well enough for simple content. But the configuration panel exposes nine distinct options, and ignoring them means you may get Markdown that is technically valid but stylistically incompatible with your target system.

• Heading Style: ATX format uses # symbols, which is what virtually every modern static site generator and Markdown renderer expects. Setext (underline-style headings with === or ---) is an older convention that certain legacy systems still prefer. If you are writing for Obsidian, Notion imports, or GitHub READMEs, stay with ATX.
• Code Block Style: The difference between indented (four-space prefix) and fenced (triple backtick) blocks matters enormously when your target renderer supports syntax highlighting. Fenced blocks let you specify the language identifier — ```python or ```bash — which indented blocks simply cannot do.
• Link Style: Inline links keep the URL right next to the anchor text, which reads cleanly for short documents. Referenced links move all URLs to the bottom of the document, making dense link-heavy HTML (like scraped documentation pages) dramatically more readable in raw form.
• Emphasis and Strong Delimiters: _italic_ versus *italic* is largely cosmetic, but some Markdown linters and style guides are strict about consistency. If your team uses markdownlint with a configured ruleset, set this before you convert rather than find-and-replace afterward.

These settings persist only within your session. If you close the tab, the defaults reset. For any repeating workflow — weekly blog migration, documentation pipeline — note your preferred settings or build a small wrapper around the underlying Turndown library with your config baked in.

How Image Tags Travel Through the Conversion

This is where the "image and photo category" framing of HTML to Markdown tools gets genuinely interesting, and genuinely complicated. The tool converts a standard <img src="photo.jpg" alt="Aerial view of Jodhpur"> cleanly into ![Aerial view of Jodhpur](photo.jpg). That one-liner is correct, accessible, and portable.

Reality, however, rarely serves up clean <img> tags from modern web pages. Three patterns break almost every HTML-to-Markdown converter, including this one:

1. Lazy loading via data-src: A CMS or e-commerce page often ships images as <img data-src="product-hero.webp" src="placeholder.gif">. The converter sees placeholder.gif — a 1x1 transparent pixel — and faithfully converts that. Your Markdown ends up pointing at nothing useful. Before converting HTML that came from a live page scrape, run a find-and-replace on data-src → src, or use a browser-based tool that evaluates JavaScript first (so the real URLs are already in the DOM).
2. Responsive images with <picture> and srcset: The <picture> element wraps multiple <source> tags for different viewport sizes, with a fallback <img> inside. Turndown (and by extension this tool) grabs only the fallback <img>. In most cases that is the correct behavior — Markdown does not have a native responsive image syntax — but if your fallback is a very low-resolution JPEG and all the high-resolution WebPs live in the <source> tags, you lose quality silently.
3. CSS background images: Anything set via background-image: url(banner.jpg) in a stylesheet or inline style is completely invisible to the converter. These images simply do not appear in the output. For editorial banners, hero sections, and decorative photo overlays loaded this way, you need to extract them manually.

When the source HTML has no alt attribute at all — which is depressingly common on older websites — the output is ![](image-url.jpg). That empty alt text is technically valid Markdown but fails WCAG accessibility standards and will trigger linter warnings in most documentation pipelines. Factor in an alt-text pass after conversion, either manually or using an AI description step before you publish.

Tables: Where Markdown's Simplicity Becomes a Hard Ceiling

The tool supports GitHub Flavored Markdown table output, which handles the straightforward case well. An HTML table with a single header row, plain text cells, and basic left/center/right alignment converts accurately. The output aligns pipe characters and dashes in a way that is human-readable in raw form.

The hard ceiling hits immediately when the source HTML uses colspan, rowspan, or nested tables. Markdown's table syntax has no concept of merged cells. When Turndown encounters these structures, it typically collapses the content linearly or drops back to raw HTML passthrough. Neither outcome is clean. For complex tabular data — pricing matrices, specification sheets, feature comparison tables from product pages — treat the converter output as a starting point and rebuild the table structure by hand, or use raw HTML inside your Markdown file (most renderers accept it).

A Practical Two-Step for Content Migration

The single most useful workflow adjustment for anyone migrating content at scale is splitting the job into two distinct stages rather than expecting one pass to handle everything.

In the first stage, clean and isolate the main content before you convert. If you are scraping live pages, strip navigation elements, sidebars, cookie banners, and footers — all of which generate meaningless Markdown debris. Tools like Trafilatura do this extraction programmatically; for one-off jobs, manually deleting that HTML from the input panel before pasting takes thirty seconds and saves significant cleanup time on the other end.

In the second stage, run the cleaned HTML through the converter with your target-appropriate settings. Because htmlmarkdown.com processes everything locally in your browser with no server-side data transmission, you can safely feed it internal content, draft copy, or proprietary product descriptions without worrying about it transiting someone else's infrastructure. That local-processing guarantee is worth more than most people consider when choosing a tool for this kind of work.

Strikethrough, Task Lists, and the GitHub Flavored Markdown Additions

Beyond the basics, the tool correctly handles several extended Markdown features that trip up simpler converters. HTML strikethrough rendered with <s>, <strike>, or <del> tags all convert to the double-tilde GFM syntax: ~~struck text~~. This matters for anyone migrating changelog documents, editorial markup, or corrected pricing information where crossed-out text carries meaning.

Checkboxes — <input type="checkbox" checked> inside a list item — convert to GFM task list syntax: - [x] item or - [ ] item. If you are moving a project tracker or an HTML-rendered checklist into Obsidian, GitHub Issues, or any GFM-compatible system, this conversion works correctly without manual intervention.

When to Reach for This Tool Versus a Programmatic Approach

For a single page or a handful of documents, htmlmarkdown.com is the right call — it is immediate, requires nothing installed, and the nine-setting configuration panel covers the options that actually vary between projects. For a content migration involving hundreds or thousands of HTML files, you need the same Turndown logic but driven programmatically. The npm package is trivial to configure in a Node.js script, and you can pass the exact same settings object you dialed in manually on the site. Think of the online tool as the configuration laboratory: get the settings right on a representative sample, then port those settings directly into your batch script.

The image-handling limitations do not become less significant at scale — if anything, they compound. A thousand-page migration with lazy-loaded images still needs a pre-processing step to rewrite data-src attributes before the Markdown converter ever runs. Build that into the pipeline from the start rather than discovering it halfway through a content audit.

What this tool does well, it does with enough configurability and transparency to be genuinely useful. What it cannot do — render CSS backgrounds, flatten merged table cells, recover images from JavaScript-rendered source attributes — is not a flaw so much as a hard boundary of what plain-text Markdown is capable of expressing. Working with those limits consciously, rather than around them blindly, is what separates a clean migration from a frustrating one.