HTML to Markdown Converter

Quick Start Guide

1. Paste HTML: Copy your HTML markup into the input area
2. Configure Options: Choose GitHub Flavored Markdown (GFM) and line break settings
3. Convert: Click "Convert to Markdown" to transform your HTML
4. Copy or Download: Use the output buttons to copy or download the Markdown
5. Try Examples: Click example buttons to see different HTML conversion scenarios

What is HTML to Markdown Conversion?

HTML to Markdown conversion transforms HTML markup into Markdown syntax, making content more readable, portable, and easier to edit in plain text editors.

Purpose: Content migration, documentation, web scraping, portability Input: HTML markup with tags and attributes Output: Clean Markdown syntax Usage: Documentation, CMS migration, content extraction, blogging

Why Convert HTML to Markdown?

Content Benefits:

• Cleaner, more readable source format
• Easier to edit in plain text editors
• Portable across platforms and tools
• Version control friendly (Git-friendly)
• Smaller file sizes without HTML overhead
• Better for documentation and README files

Common Scenarios:

• Migrating from WordPress/CMS to static site generators
• Converting web pages for documentation
• Extracting content from HTML emails
• Creating README files from HTML docs
• Web scraping for content extraction
• Converting WYSIWYG editor output to Markdown

GitHub Flavored Markdown (GFM)

GFM is an extension of standard Markdown with additional features used on GitHub, GitLab, and many platforms.

Standard Markdown supports:

• Headings (# ## ###)
• Bold (text) and italic (text)
• Links text
• Images
• Lists (ordered and unordered)
• Code blocks and inline code
• Blockquotes (>)
• Horizontal rules (---)

GFM adds:

• Tables with pipes (|)
• Strikethrough (text)
• Task lists (- [ ] item)
• Automatic URL linking
• Syntax highlighting in code blocks

When to enable GFM:

• Converting for GitHub/GitLab repositories
• Need table support
• Want strikethrough formatting
• Target platform supports GFM

Conversion Options Explained

GitHub Flavored Markdown (GFM)

Enabled (recommended):

• Converts HTML tables to Markdown tables
• Converts strikethrough tags to text
• Better compatibility with GitHub/GitLab
• More feature-rich output

Disabled (standard Markdown):

• Tables remain as HTML or are removed
• Strikethrough not supported
• Smaller, simpler output
• Better for basic Markdown parsers

Preserve Line Breaks

Enabled:

• Converts <br> to two spaces + newline (Markdown hard break)
• Preserves exact line break positions
• Better for poetry, addresses, formatted text

Disabled (default):

• Converts <br> to single newline
• More compact output
• Better for paragraph-based content

When to enable:

• Poetry or verse formatting
• Addresses or contact information
• Intentional line breaks matter
• Exact formatting preservation needed

Common Use Cases

1. Converting Web Pages to Markdown

Purpose: Extract clean content from HTML pages for documentation

Before:

<h1>Getting Started</h1>
<p>Welcome to our <strong>amazing</strong> documentation.</p>
<ul>
  <li>Feature one</li>
  <li>Feature two</li>
</ul>

After:

# Getting Started

Welcome to our **amazing** documentation.

- Feature one
- Feature two

2. Converting HTML Lists and Links

Purpose: Transform HTML navigation or link lists to Markdown

Before:

<h2>Resources</h2>
<ul>
  <li><a href="https://docs.example.com">Documentation</a></li>
  <li><a href="https://github.com/user/repo">GitHub Repo</a></li>
  <li><a href="https://blog.example.com">Blog</a></li>
</ul>

After:

## Resources

- [Documentation](https://docs.example.com)
- [GitHub Repo](https://github.com/user/repo)
- [Blog](https://blog.example.com)

3. Converting Code Blocks

Purpose: Convert HTML code examples to Markdown format

Before:

<h3>Example Code</h3>
<pre><code class="language-python">def hello():
    print("Hello, World!")
hello()</code></pre>

After:

### Example Code

` ` `python
def hello():
    print("Hello, World!")
hello()
` ` `

Note: Remove spaces between backticks in actual use.

4. Converting Tables (GFM Mode)

Purpose: Transform HTML tables to Markdown format

Before:

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Role</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alice</td>
      <td>Developer</td>
    </tr>
    <tr>
      <td>Bob</td>
      <td>Designer</td>
    </tr>
  </tbody>
</table>

After (with GFM enabled):

| Name | Role |
| --- | --- |
| Alice | Developer |
| Bob | Designer |

5. Converting Blockquotes

Purpose: Transform HTML quotes to Markdown blockquotes

Before:

<blockquote>
  <p>The best way to predict the future is to invent it.</p>
  <p>— Alan Kay</p>
</blockquote>

After:

> The best way to predict the future is to invent it.
> — Alan Kay

6. Converting Images and Media

Purpose: Transform image tags to Markdown syntax

Before:

<h2>Screenshots</h2>
<img src="screenshot.png" alt="App Dashboard" />
<p>Above is our beautiful dashboard.</p>

After:

## Screenshots

![App Dashboard](screenshot.png)

Above is our beautiful dashboard.

Features

Core Functionality

• Complete HTML Parsing: Handles all common HTML elements
• Clean Output: Removes unnecessary HTML artifacts
• Whitespace Normalization: Cleans up excessive blank lines
• Entity Decoding: Converts HTML entities (&, <, etc.)
• Nested Structure: Maintains document hierarchy
• Link Preservation: Keeps all hyperlinks intact

Supported HTML Elements

Text Formatting:

• Headings (h1, h2, h3, h4, h5, h6)
• Paragraphs (p)
• Bold (strong, b)
• Italic (em, i)
• Strikethrough (del, s, strike) - GFM only
• Inline code (code)
• Code blocks (pre > code)

Lists:

• Unordered lists (ul > li)
• Ordered lists (ol > li)
• Nested lists

Links & Media:

• Hyperlinks (a href)
• Images (img src/alt)

Block Elements:

• Blockquotes (blockquote)
• Horizontal rules (hr)
• Tables (table, thead, tbody, tr, th, td) - GFM only

Other:

• Line breaks (br)
• HTML comments (removed)
• Inline styles (removed)

Conversion Options

GitHub Flavored Markdown:

• Enable: Convert tables and strikethrough
• Disable: Standard Markdown only

Preserve Line Breaks:

• Enable: <br> becomes two spaces + newline
• Disable: <br> becomes single newline

Best Practices

1. Clean Your HTML First

Recommendation: Remove unnecessary HTML before conversion

Good HTML:

<h1>Title</h1>
<p>Paragraph text.</p>

Messy HTML:

<div><span><h1 style="color: red;">Title</h1></span></div>
<p class="text" id="p1" data-foo="bar">Paragraph text.</p>

The converter removes inline styles and attributes, but cleaner input produces cleaner output.

2. Enable GFM for Modern Platforms

Use GFM for:

• GitHub/GitLab repositories
• Documentation sites (Hugo, Jekyll, MkDocs)
• Platforms that support GFM
• When you need tables

Use Standard Markdown for:

• Email (some clients)
• Basic Markdown parsers
• Maximum compatibility

3. Check the Output

After conversion:

1. Review the Markdown output
2. Test in your target platform
3. Fix any formatting issues
4. Check links and images work

4. Handle Complex HTML

For complex HTML:

• Simplify HTML structure first
• Remove unnecessary wrapper divs
• Use semantic HTML (proper h1, h2, p, etc.)
• Test with examples before bulk conversion

5. Preserve Source URLs

For images and links:

• Ensure URLs are absolute (https://...) not relative (../images)
• Test image URLs are accessible
• Update paths if migrating to new domain

Technical Details

How HTML to Markdown Conversion Works

1. Parse HTML input character by character
2. Identify HTML tags and structure
3. Match opening and closing tags
4. Convert each HTML element to Markdown equivalent
5. Remove HTML comments and unnecessary tags
6. Decode HTML entities (& to &)
7. Clean up excessive whitespace and newlines
8. Output clean Markdown syntax

Conversion Mapping

HTML	Markdown
<h1>Title</h1>	# Title
<h2>Heading</h2>	## Heading
<strong>bold</strong>	**bold**
<em>italic</em>	*italic*
<a href="url">text</a>	[text](url)
<img src="url" alt="text">	
<code>code</code>	`code`
<ul><li>item</li></ul>	- item
<ol><li>item</li></ol>	1. item
<blockquote>quote</blockquote>	> quote
<hr>	---

Limitations

This is a basic converter:

• Uses regex-based parsing (not full HTML parser)
• May not handle deeply nested HTML perfectly
• Complex tables may need manual adjustment
• Some edge cases require manual fixes

For production conversion:

• Turndown.js: Full HTML to Markdown with plugins
• Pandoc: Universal document converter
• html-to-md: Node.js library with AST parsing

This tool is best for:

• Quick one-off conversions
• Simple to moderate HTML
• Web content extraction
• Learning Markdown syntax
• Privacy-focused conversion (100% local)

Browser Compatibility

Supported browsers:

• ✅ Chrome 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+
• ✅ Opera 76+

Works on:

• Desktop: Windows, macOS, Linux
• Mobile: iOS Safari, Chrome Android
• Tablets: iPad, Android tablets

Privacy & Security

Client-Side Processing

• 100% Local: All conversion in your browser
• No Uploads: HTML never sent to server
• No Storage: Nothing saved or cached
• No Tracking: No analytics on your HTML
• No Accounts: No login required

Safe for Sensitive Content

• ✅ Internal documentation
• ✅ Private web pages
• ✅ Email HTML content
• ✅ Proprietary content
• ✅ Personal notes

Note: The converter only processes text. It does not execute JavaScript or load external resources from your HTML.

Comparison with Other Tools

HTML to Markdown Converter vs Turndown.js

This Tool:

• ✅ Browser-based, instant
• ✅ No installation needed
• ✅ Privacy-focused (100% local)
• ✅ Simple, clean interface
• ❌ Basic parsing
• ❌ Limited customization

Turndown.js:

• ✅ Full HTML parser
• ✅ Plugin system
• ✅ Highly customizable
• ✅ Handles complex HTML
• ❌ Requires coding/setup
• ❌ Node.js or build step

When to use this tool: Quick conversions, simple HTML, privacy

When to use Turndown: Production pipelines, complex HTML, automation

HTML to Markdown vs Pandoc

This Tool:

• ✅ Web-based, no install
• ✅ Instant conversion
• ✅ User-friendly
• ❌ HTML to Markdown only

Pandoc:

• ✅ Converts 40+ formats
• ✅ Command-line power
• ✅ Batch processing
• ❌ Installation required
• ❌ Steeper learning curve

When to use this tool: Browser convenience, quick web conversions

When to use Pandoc: Multiple formats, automation, bulk processing

Integration Tips

Using Converted Markdown

1. Copy to Editor:

• Convert your HTML
• Click "Copy Markdown"
• Paste into VS Code, Typora, Obsidian, etc.
• Edit as needed

2. Download File:

• Convert your HTML
• Click "Download .md"
• Save to your documentation folder
• Commit to Git repository

3. Integrate with Static Site Generators:

# After converting HTML to Markdown
# Move to your content folder
mv converted.md content/posts/my-post.md

# Build your site (Hugo example)
hugo server

# Or Jekyll
jekyll serve

Batch Conversion Workflow

For multiple HTML files:

1. Convert one file to test output quality
2. Adjust HTML if needed (remove wrappers, clean structure)
3. Convert remaining files one by one
4. Review each output for accuracy
5. Make manual adjustments as needed

Alternative: Use Turndown.js or Pandoc for scripted batch conversion

Content Migration Example

WordPress to Jekyll:

1. Export WordPress content as HTML
2. Convert each post HTML to Markdown using this tool
3. Add Jekyll front matter to each .md file
4. Place in _posts/ folder
5. Run Jekyll build

CMS to Static Site:

1. Extract HTML content from CMS
2. Clean HTML (remove navigation, footers, etc.)
3. Convert to Markdown
4. Add static site generator metadata
5. Rebuild static site

---

Note: For production use with complex HTML or automation needs, consider using Turndown.js (JavaScript library) or Pandoc (universal converter). This tool is perfect for quick conversions, simple HTML, and privacy-focused use cases.