HTML to Markdown: Complete Conversion Guide + Free Online Tool
If you've ever copied content from a website into a GitHub README, a documentation tool, or a static site generator, you've run into this problem: the content is HTML, but you need Markdown. Manually reformatting it is tedious. This guide explains exactly what the conversion involves, common pitfalls to avoid, and how to do it instantly, for free.
⚡ Quick Answer
Paste your HTML into our free HTML to Markdown Converter and get clean Markdown output instantly: no signup, no server, 100% private.
HTML vs Markdown: What's the Difference?
Both formats describe structured text, but they serve very different purposes and audiences.
🏗️ HTML
HyperText Markup Language, the language browsers use to render web pages. Uses verbose tags like <h1>, <p>, and <a href="...">.
- • Websites and web apps
- • Email templates
- • CMS platforms (WordPress, Drupal)
- • Full layout and style control
📝 Markdown
Lightweight plain-text format designed to be readable without rendering. Uses symbols like #, **bold**, and [link](url).
- • GitHub READMEs and wikis
- • Static site generators (Next.js, Astro, Hugo)
- • Documentation (Docusaurus, GitBook, MkDocs)
- • Note-taking apps (Obsidian, Notion, Bear)
Both formats can express the same content, including headings, bold text, links, and lists, but Markdown is far simpler to write and read as plain text, while HTML offers precise control over layout and styling.
When Do You Need to Convert HTML to Markdown?
The most common scenarios where you'll need to convert HTML into Markdown:
- →Moving content to GitHub
GitHub renders Markdown natively in READMEs, wikis, and issues. HTML from existing docs needs converting.
- →Migrating a blog or CMS
Moving from WordPress to a static site generator (Next.js, Astro, Hugo) often means converting stored HTML to Markdown files.
- →Writing technical documentation
Tools like Docusaurus, MkDocs, and GitBook use Markdown. HTML from existing sources needs converting.
- →Saving content to a notes app
Copying HTML email content or web articles into Obsidian, Bear, or Notion works much better in Markdown.
- →Feeding content to AI models
LLMs process Markdown more cleanly than raw HTML when you're providing structured context or documents.
HTML to Markdown Conversion Reference Table
Here's a quick reference for the most common HTML element conversions. This covers 14 of the most-used HTML elements and their Markdown equivalents.
| HTML | Markdown | Result |
|---|---|---|
| <h1>Title</h1> | # Title | Heading 1 |
| <h2>Subtitle</h2> | ## Subtitle | Heading 2 |
| <h3>Section</h3> | ### Section | Heading 3 |
| <strong>text</strong> | **text** | Bold |
| <em>text</em> | *text* | Italic |
| <a href="url">link</a> | [link](url) | Hyperlink |
| <img src="x" alt="y"> |  | Image |
| <code>snippet</code> | `snippet` | Inline code |
| <pre><code>block</code></pre> | ```\nblock\n``` | Code block |
| <blockquote>text</blockquote> | > text | Blockquote |
| <ul><li>item</li></ul> | - item | Bullet list |
| <ol><li>item</li></ol> | 1. item | Numbered list |
| <hr> | --- | Horizontal rule |
| <del>text</del> | ~~text~~ | Strikethrough |
How to Convert HTML to Markdown Online (Free)
The fastest way is to use our HTML to Markdown Converter. It runs entirely in your browser, so nothing is uploaded to any server.
📋 Step-by-Step Instructions
- Go to the HTML to Markdown Converter tool.
- Paste your HTML code into the left panel (or click Load sample to try an example).
- The Markdown output appears instantly in the right panel, with no button to click.
- Click Copy Markdown to copy the result to your clipboard.
- Paste into your GitHub README, documentation tool, or notes app.
100% Private
Nothing leaves your browser. No data is uploaded to any server.
Instant
Output updates as you type, with no convert button needed.
Completely Free
No signup, no account, no limits. Use it as much as you need.
Common Issues When Converting HTML to Markdown
Most HTML converts cleanly, but a few specific situations need special handling.
1. Inline Styles Are Dropped
Markdown has no equivalent for inline CSS like color: red or font-size: 18px. These are stripped during conversion. If you need styled text, keep it in HTML or use a Markdown renderer that supports raw HTML passthrough.
2. Complex Nested Structures
Deeply nested HTML (tables inside divs inside sections) can produce messy output. The best approach is to convert the main content area only, not the full page including nav, footer, and sidebars.
3. JavaScript-Rendered Content
If the page renders content via JavaScript (React, Angular, Vue), View Page Source shows the template, not the rendered content. Instead, right-click → Inspect → copy the rendered HTML from DevTools.
4. Tables with Merged Cells
Standard Markdown table syntax doesn't support colspan or rowspan. Most converters (including ours) produce standard Markdown table syntax that works in GitHub, GitBook, and most renderers, but merged cells are flattened.
Converting HTML to Markdown Programmatically
If you need to automate the conversion (e.g., batch processing files or a CI pipeline), here are the most popular options by language:
JavaScript / Node.js
The turndown library is the most popular choice, and it's the same engine our online tool uses:
npm install turndown
const TurndownService = require('turndown');
const turndown = new TurndownService();
const markdown = turndown.convert('<h1>Hello</h1><p>World</p>');
console.log(markdown);
// # Hello
//
// WorldPython
Use the markdownify library:
pip install markdownify
from markdownify import markdownify as md
result = md('<h1>Hello</h1><p>World</p>')
print(result)
# # Hello
#
# WorldCommand Line (Pandoc)
Pandoc is the universal document converter. It handles batch files efficiently:
pandoc input.html -f html -t markdown -o output.md
# Batch convert all HTML files in a folder:
for f in *.html; do pandoc "$f" -f html -t markdown -o "${f%.html}.md"; doneHTML vs Markdown: Which Should You Use?
The right format depends entirely on your context and audience:
✅ Use HTML when you need:
- • Precise layout control and custom styling
- • Complex forms, modals, or interactive elements
- • Browser-specific features and multimedia
- • Email templates (email clients parse HTML, not Markdown)
✅ Use Markdown when you need:
- • Plain-text readability without rendering
- • Git-tracked content (READMEs, wikis, docs)
- • Static site generator input (Next.js, Astro, Hugo)
- • Simple, portable content that travels across tools
Many modern tools (GitHub, Notion, Obsidian) accept both, but Markdown is generally preferred for its simplicity and portability. If you ever need to go the reverse direction, our Markdown to HTML Converter handles that too.