HTML to Markdown Conversion Guide: Complete Tutorial for Web Developers 2025

Conversion Process Steps:

1. HTML Parsing: The converter reads and parses your HTML code structure
2. Element Mapping: HTML tags are mapped to their Markdown equivalents:
   • <h1> to #, <h2> to ##, etc.
   • <p> to plain paragraphs with line breaks
   • <strong> to **text**
   • <em> to *text*
   • <a> to [text](url)
   • <img> to ![alt](src)
3. Content Extraction: Text content is extracted and cleaned
4. Attribute Handling: Non-critical attributes are removed or preserved in HTML comments
5. Output Generation: Clean Markdown syntax is generated

HTML: <h1>Heading 1</h1>
Markdown: # Heading 1

HTML: <h2>Heading 2</h2>
Markdown: ## Heading 2

HTML: <p>Paragraph</p>
Markdown: Paragraph

HTML: <strong>Bold</strong>
Markdown: **Bold**

HTML: <em>Italic</em>
Markdown: *Italic*

HTML: <a href="url">Link</a>
Markdown: [Link](url)

HTML: <ul><li>Item</li></ul>
Markdown: * Item

HTML: <ol><li>Item</li></ol>
Markdown: 1. Item

HTML: <img src="image.jpg" alt="Description">
Markdown: ![Description](image.jpg)

1. Go to our HTML to Markdown converter
2. Paste your HTML code in the input field
3. See the live Markdown preview
4. Customize options (GitHub Flavored Markdown, etc.)
5. Copy the result or download as a file
6. Edit the Markdown as needed

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

For batch conversion (multiple files):

for file in *.html; do
  pandoc -f html -t markdown "$file" -o "${file%.html}.md"
done

const TurndownService = require('turndown');
const fs = require('fs');

// Read HTML file
const html = fs.readFileSync('input.html', 'utf-8');

// Convert to Markdown
const turndownService = new TurndownService();
const markdown = turndownService.turndown(html);

// Write to file
fs.writeFileSync('output.md', markdown);

import html2text
import sys

# Read HTML file
with open('input.html', 'r', encoding='utf-8') as f:
    html = f.read()

# Convert to Markdown
h = html2text.HTML2Text()
h.ignore_links = False
markdown = h.handle(html)

# Write to file
with open('output.md', 'w', encoding='utf-8') as f:
    f.write(markdown)

HTML:
<table>
  <tr><th>Header 1</th><th>Header 2</th></tr>
  <tr><td>Data 1</td><td>Data 2</td></tr>
</table>

Markdown:
| Header 1 | Header 2 |
|----------|----------|
| Data 1   | Data 2   |

HTML Video:
<video src="video.mp4"></video>

Markdown approach:
[Watch Video](video.mp4)

For embeds, preserve HTML:
<iframe src="https://example.com"></iframe>

HTML Comments convert to Markdown comments:
<!-- This is a comment -->

• Clean Your HTML: Remove unnecessary divs, spans, and inline styles
• Validate HTML: Fix broken tags and structure issues first
• Plan Your Output: Decide on Markdown flavor (standard, GitHub, CommonMark)
• Backup Original: Always keep the original HTML files
• Identify Limitations: Note elements that won't convert perfectly

• Test Conversion: Start with small samples before batch processing
• Preview Results: Use live preview if available
• Preserve Links: Ensure URL and alt text integrity
• Handle Special Characters: Check for encoding issues
• Maintain Structure: Preserve document hierarchy and relationships

• Review and Edit: Manually check converted content for quality
• Fix Formatting Issues: Correct any conversion artifacts
• Update Internal Links: Adjust links for new Markdown structure
• Add Metadata: Include front matter (title, date, author, tags)
• Test Links: Verify all external and internal links work
• Update Related Content: Update other documents that reference converted files

Using a Bash Script with Pandoc:

#!/bin/bash
SOURCE_DIR="./html_files"
OUTPUT_DIR="./markdown_files"

mkdir -p "$OUTPUT_DIR"

for html_file in "$SOURCE_DIR"/*.html; do
    filename=$(basename "$html_file" .html)
    pandoc -f html -t markdown \
        --wrap=none \
        "$html_file" \
        -o "$OUTPUT_DIR/$filename.md"
    echo "Converted: $filename"
done

echo "Batch conversion complete!"

Node.js Custom Converter Example:

const TurndownService = require('turndown');
const fs = require('fs');

const turndownService = new TurndownService({
    headingStyle: 'atx',
    codeBlockStyle: 'fenced',
    bulletListMarker: '-'
});

// Add custom rules
turndownService.addRule('strikethrough', {
    filter: ['s', 'del'],
    replacement: content => `~~${content}~~`
});

// Batch convert
const files = fs.readdirSync('./html').filter(f => f.endsWith('.html'));
files.forEach(file => {
    const html = fs.readFileSync(`./html/${file}`, 'utf-8');
    const md = turndownService.turndown(html);
    const filename = file.replace('.html', '.md');
    fs.writeFileSync(`./markdown/${filename}`, md);
});

Most Markdown processors allow HTML passthrough:

This is Markdown text.

<div class="special-box">
This HTML block will be preserved as-is in the output.
</div>

More Markdown text continues here.

---
title: "My Article Title"
date: 2025-12-28
author: "Author Name"
tags: ["tag1", "tag2"]
slug: "article-slug"
---

# Main Content Heading

Your article content here...

Standard Markdown (CommonMark)

Most compatible, minimalist feature set. Best for universal compatibility.

GitHub Flavored Markdown (GFM)

Adds tables, task lists, strikethrough, and autolinks. Excellent for documentation. Supported by GitHub, GitLab, and many others.

MultiMarkdown

Extends with footnotes, citations, and metadata. Good for academic writing.

Pandoc's Extended Markdown

Supports definition lists, pipe tables, footnotes, and more. Most powerful option.