You're migrating a WordPress blog to a Next.js static site, importing old documentation into Obsidian, or turning a web page into a GitHub README. All of these share the same problem: you have HTML and need Markdown. This guide covers every practical approach — from a free online converter to command-line tools.
Advertisement
5 Common Scenarios That Need HTML → Markdown
1. Migrating a CMS to a static site generator
WordPress, Drupal, and Ghost all export content as HTML. Static site generators like Hugo, Gatsby, Astro, and Next.js use Markdown (or MDX) for content. Converting HTML posts to Markdown is the first step in any CMS migration.
2. Importing content into Obsidian or Notion
Both tools use Markdown as their native format. If you have years of notes stored as HTML (from an old CMS, exported emails, or web clips), converting to Markdown makes them importable.
3. Writing GitHub or GitLab README files
GitHub renders Markdown in README.md files. If your existing documentation is in HTML (from a Confluence export, an internal wiki, or a documentation site), converting it to Markdown is faster than rewriting from scratch.
4. Converting HTML emails to meeting notes
HTML-formatted emails with tables, lists, and headings can be converted to clean Markdown to paste into a project wiki or documentation system.
5. Building MDX content from existing HTML
MDX (Markdown + JSX) files for React-based sites start with Markdown. Converting legacy HTML content to Markdown gives you a base to work from before adding JSX components.
⬇️ Convert HTML to Markdown Instantly — Free & Private
Paste any HTML into the left panel and get clean Markdown on the right. Supports headings, lists, links, code blocks, tables, bold, and italic. Options for heading style, bullet marker, and code block format. Everything runs in your browser — nothing uploaded.
⬇️ Open HTML to Markdown Converter →Advertisement
What Gets Converted — and What Doesn't
✓ Converts cleanly
| HTML | Markdown |
|---|---|
| <h1> – <h6> | # through ###### |
| <strong>, <b> | **bold** |
| <em>, <i> | *italic* |
| <a href="..."> | [text](url) |
| <ul> + <li> | - item |
| <ol> + <li> | 1. item |
| <code> | `inline code` |
| <pre><code> | ```code block``` |
| <blockquote> | > quote |
| <table> | Markdown table |
| <img alt="..." src="..."> |  |
| <hr> | --- |
✗ Not supported in Markdown
- ✗Inline styles — color, font-size, background-color — Markdown has no styling
- ✗JavaScript — Scripts are stripped entirely
- ✗Complex layouts — div, flexbox, grid collapse to plain text content
- ✗Inline SVG — SVG markup is removed
- ✗iframe / embed — External embeds cannot be represented in Markdown
- ✗Form elements — input, select, button are not part of Markdown
- ✗Custom classes — class= attributes have no Markdown equivalent
Step-by-Step: Using the Online Converter
- Open the HTML to Markdown Converter
- Paste your HTML into the left panel — the Markdown output appears on the right immediately
- Adjust options if needed: heading style (ATX
#vs Setext underline), bullet marker, code block style - Click Copy Markdown to copy the result to your clipboard
For best results, paste only the main content HTML (article body, blog post body) rather than the full page source including <head>, navigation, and footer.
Command-Line Alternatives
Pandoc (most powerful)
Pandoc is the universal document converter and handles HTML → Markdown with high fidelity:
pandoc -f html -t markdown input.html -o output.mdNode.js (Turndown library)
npm install turndown
node -e "const T=require('turndown');console.log(new T().turndown(require('fs').readFileSync('input.html','utf8')))" > output.mdFrequently Asked Questions
Why does my converted Markdown have extra backslashes?
Markdown uses certain characters (*,_,[, etc.) as formatting syntax. When these appear in plain text content, the converter escapes them with a backslash to prevent unintended formatting. This is correct Markdown — most renderers handle it fine.
Can I convert a full WordPress export to Markdown?
For a full WordPress migration, tools like wordpress-export-to-markdown (npm package) are better suited — they process the entire XML export file. The online converter is best for individual posts or smaller pieces of HTML content.
Which Markdown flavour does the output use?
The default output uses CommonMark-compatible Markdown (GitHub Flavored Markdown when tables are present). The ATX heading style and fenced code blocks are the GitHub standard and work in virtually all modern Markdown renderers.
Is the conversion reversible — can I convert back to HTML?
Yes — use the Markdown to HTML Converter to go the other direction. Note that any styling or structure lost during HTML → Markdown conversion (inline styles, layouts) will not be recovered.