How to Convert HTML to Markdown (3 Ways)

Search "convert HTML to Markdown" and you'll get three kinds of answers — an online converter, a Pandoc command, and a code snippet — usually with no guidance on which to actually use. They're not interchangeable. The right choice depends entirely on whether you have HTML source, a folder full of files, or a live page in front of you. We build a Markdown converter for a living, so here are the three ways that genuinely work, when each one wins, and the gotchas that quietly mangle your output.

The 3 ways to convert HTML to Markdown at a glance

There's no single "best" method — there's a best method for your situation. Here's the short version before we dig into each one:

The deciding question is what you're starting from. Have a chunk of HTML on your clipboard? Use the online converter. Have a directory of .html files to migrate? Use Pandoc. Looking at a page in your browser and want it as Markdown? Use the extension. We'll take them in that order.

Way 1 — Paste it into an online HTML to Markdown converter

If you already have the HTML — copied from "View Source," an API response, an email export, a CMS field — the fastest path is an online HTML to Markdown converter. Paste the markup, get clean Markdown back, copy it out. No install, no command line, done in seconds.

This is the right tool for one-off conversions: a single snippet, a table you need in a README, a fragment you're pasting into a doc. Our own online editor does this with a live preview — paste HTML on one side, watch the Markdown render on the other, and tweak before you copy. Because it runs the conversion client-side in your browser (on the same Turndown engine our extension uses), the HTML you paste never leaves your machine — a real consideration if the markup contains anything private.

Where online converters fall down: volume and live pages. Pasting 200 files one at a time is misery, and you can't paste a page you don't have the source for. That's what the next two methods are for.

Way 2 — Convert HTML to Markdown with Pandoc on the command line

When you have HTML on disk — one big file or a whole folder — Pandoc is the workhorse. It's a free, open-source document converter that handles HTML to Markdown (and dozens of other formats) reliably, and it's built for scripting.

Install it once (brew install pandoc on macOS, choco install pandoc or the official installer on Windows, apt install pandoc on most Linux distros), then convert a single file:

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

A few flags do most of the heavy lifting:

• -t gfm outputs GitHub-Flavored Markdown, so tables and task lists survive. Use -t markdown_strict if you need plain CommonMark instead.
• --wrap=none stops Pandoc from hard-wrapping lines at 72 characters, which otherwise litters your output with mid-sentence line breaks.

The reason to reach for Pandoc is batch conversion. Migrating a documentation site or a folder of exported articles? One line turns the whole directory into Markdown:

for f in *.html; do pandoc -f html -t gfm --wrap=none "$f" -o "${f%.html}.md"; done

You can even pull a remote page through it by piping curl output into Pandoc:

curl -sL https://example.com/article | pandoc -f html -t gfm -o article.md

The trade-off is honest: Pandoc needs to be installed, it has a learning curve, and — like any source-level converter — it converts everything it's given. Feed it a full page and you'll get the navigation, the footer, and the cookie banner right alongside the article, because it has no concept of what the "main content" is. For raw files that's fine; for a live page, the extension solves exactly that.

Way 3 — Capture a live page with a browser extension

The case the first two methods can't handle well: you're looking at a page and you want it as Markdown, but you don't have clean source — it's JavaScript-rendered, buried in <div> soup, or wrapped in navigation and ads. That's where a browser extension wins.

Instead of asking you to find the HTML, the extension reads the page you're already on — the fully rendered DOM — and converts it in one click. Three things make this different from pasting source into a converter:

1. It captures JavaScript-rendered content. Because it works on the live DOM, single-page apps and lazy-loaded sections come through intact, where "View Source" would show you an empty shell.
2. It strips the page chrome. It extracts the main content — headings, paragraphs, lists, code, tables, images — and drops the nav, sidebars, and footers before converting, so you don't spend ten minutes deleting menus.
3. It fixes links automatically. Relative URLs like /docs/intro are resolved to absolute links so they don't break the moment the Markdown leaves the site.

There's also a select-area tool for when you only want one section — draw a box around a single table or code sample and it converts just that. We covered this whole live-page workflow in depth in Convert Any Webpage to Markdown in One Click.

Which method should you use?

Map it to what you're starting from and the choice makes itself:

• A snippet of HTML you already have → the online converter. Fastest for one-off jobs, nothing to install, conversion stays in your browser.
• A folder of HTML files, or a repeatable job → Pandoc. It's scriptable, handles batches, and slots into a docs pipeline or a Makefile.
• A page you're reading in the browser → the extension. It's the only one that captures rendered content and strips the page chrome for you.
• A conversion step inside your own app or script → a library (see the FAQ): Turndown in Node, markdownify or html2text in Python.

Common mistakes (and how to avoid them)

Whichever method you pick, the same handful of issues trip people up:

• Broken relative links. A link like /pricing becomes a dead link once the Markdown leaves the original site. Resolve relative URLs to absolute ones — the extension does this automatically; with Pandoc, start from the page's real base URL.
• Lost code-fence languages. Weaker converters turn a highlighted js block into an unlabeled fence, so your renderer can't color it. Check that the language hint survived the conversion.
• Converting the chrome along with the content. Source-level tools (online converters and Pandoc) convert everything you hand them, nav and ads included. Trim the HTML down to the article first, or use the extension's main-content extraction.
• Hard-wrapped lines from Pandoc. Forget --wrap=none and you'll get line breaks mid-sentence that read fine in Markdown but break diffs and editing.
• Expecting pixel-perfect layout. Markdown is structural, not visual. Multi-column layouts and custom styling flatten to one readable column — that's the format working as intended.

Whichever method you use, run the output past the 9 rules for clean Markdown before you commit it — converted Markdown is exactly where unlabelled code fences and broken links creep in.

FAQ

What is the fastest way to convert HTML to Markdown? For a one-off snippet, paste the HTML into an online converter and copy the Markdown back — a few seconds, no install. For many files at once, Pandoc on the command line is faster overall. For a live web page you're looking at, the one-click extension wins.

How do I convert HTML to Markdown with Pandoc? Install Pandoc, then run pandoc -f html -t gfm input.html -o output.md. Use -t gfm for GitHub-Flavored Markdown (tables, task lists) and add --wrap=none so lines aren't hard-wrapped. To convert a whole folder, loop over the files in a short shell command.

Can I convert HTML to Markdown in Python or Node? Yes. In Node, the Turndown library converts an HTML string to Markdown in a couple of lines — it's the same engine our tools use. In Python, markdownify or html2text do the same job. Reach for a library when conversion is one step in a larger automated pipeline.

How do I batch convert many HTML files to Markdown? Use Pandoc in a shell loop (for f in *.html; do pandoc -f html -t gfm "$f" -o "${f%.html}.md"; done) or a script built on a converter library. Both turn a directory of HTML into a parallel directory of .md files without manual copy-paste.

Does converting HTML to Markdown keep links, images, and code blocks? A good converter preserves all three: links become [text](url), images become ![alt](src), and <pre><code> becomes a fenced code block. The two things to watch are relative URLs (resolve them to absolute) and the code-fence language hint, which weaker converters drop.

There's no universally best way to convert HTML to Markdown — there's the one that fits what's in front of you. Have the source? Paste it into the editor. Have a folder? Script it with Pandoc. Looking at a live page? Grab the extension and do it in one click.