HTML to Markdown Converter

What does the HTML to Markdown Converter do?

The HTML to Markdown Converter transforms raw HTML markup, DOM hierarchies, and rich text documents into clean GitHub Flavored Markdown (GFM). It accurately maps headings, lists, inline formatting (**bold**, *italic*), code fences (code blocks), hyperlinks, and images into lightweight Markdown documents.

Core Concepts

Understanding HTML to Markdown mapping rules:

• Heading & Block Parsing: Converts <h1>-<h6> tags into # through ###### Markdown lines.
• Inline Styling & Media: Translates <strong>/<b> into **, <em>/<i> into *, and <a>/<img> tags into standard link and image Markdown syntax.
• Code & List Blocks: Translates <pre><code> structures into triple-backtick fenced code blocks and maps <li> elements to bulleted list items.

How to use the tool?

1. Paste HTML Document: Enter or paste your raw HTML snippet into the editor or click Load Sample.
2. Execute Conversion: Click Convert to Markdown to parse and transform DOM elements.
3. Copy & Export: Click Copy or Download to save your GitHub Flavored Markdown document.

Related Developer Utilities

If you work with documentation generation, web scraping, and HTML processing, explore these complementary tools:

• HTML Tag Stripper: Strip all HTML tags to extract raw unformatted plain text.
• HTML Formatter & Beautifier: Indent and format messy HTML markup code.
• HTML Syntax Validator: Validate HTML documents against W3C standards.
• HTML Entity Decoder: Decode HTML entities back to raw text characters.

REST API Integration

Blueutils provides a free REST API endpoint (POST https://blueutils.com/api/html/html-to-markdown) to programmatically convert HTML markup code into clean GitHub Flavored Markdown (GFM).

API Request Parameters

API Request Payload Examples

cURL

curl -X POST https://blueutils.com/api/html/html-to-markdown \
  -H "Content-Type: application/json" \
  -d '{
    "rawText": "<h1>Title</h1><p>This is <strong>bold</strong> text.</p>"
  }'

Python

import requests

url = "https://blueutils.com/api/html/html-to-markdown"
payload = { "rawText": "<h1>Title</h1><p>This is <strong>bold</strong> text.</p>" }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String jsonPayload = """
            {
                "rawText": "<h1>Title</h1><p>This is <strong>bold</strong> text.</p>"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://blueutils.com/api/html/html-to-markdown"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

API Response Parameters

API Response Payload Examples

Success Response (HTTP 200 OK)

{
  "isValid": true,
  "markdownText": "# Title\n\nThis is **bold** text.",
  "result": "# Title\n\nThis is **bold** text."
}

Validation Failure Response (HTTP 400 Bad Request)

{
  "isValid": false,
  "error": "Invalid input: HTML payload to convert cannot be empty."
}

Rate Limit Exceeded Response (HTTP 429 Too Many Requests)

{
  "error": "API rate limit exceeded. Please wait or contact support@blueutils.com."
}

Why use an API to convert HTML to Markdown?

Integrating the HTML to Markdown API into web scrapers, static site generator pipelines, or AI prompt preprocessors provides key benefits:

• Rapid Script Validation: Converts web pages and CMS articles into Markdown before writing to documentation repositories.
• Optimized Token Efficiency for AI Agents: LLMs ingest Markdown far more efficiently than verbose HTML markup with nested <div> and <section> tags, cutting input tokens by up to 60%.
• Deterministic Accuracy Without Hallucinations: Ensures 100% accurate heading levels, link URLs, and code block formatting.

Native Usage

How to convert HTML to Markdown locally in terminal environments or scripts:

Windows (CMD / PowerShell)

# Convert HTML headings to Markdown in PowerShell
(Get-Content -Path .\index.html) -replace '<h1>', '# ' -replace '</h1>', '' | Set-Content index.md

Linux / Unix (Bash)

# Convert HTML to Markdown using pandoc in Linux
pandoc -f html -t gfm index.html -o index.md

Python

Using html2text in Python:

import html2text

html_content = "<h1>Title</h1><p>Paragraph with <strong>bold</strong> text.</p>"
converter = html2text.HTML2Text()
converter.ignore_links = False
print(converter.handle(html_content))

Java

Using Java regex or Flexmark:

import java.nio.file.Files;
import java.nio.file.Paths;

public class HtmlToMarkdownExample {
    public static void main(String[] args) throws Exception {
        String html = new String(Files.readAllBytes(Paths.get("index.html")));
        String md = html.replaceAll("(?i)<h1>(.*?)</h1>", "# $1\n")
                        .replaceAll("(?i)<p>(.*?)</p>", "$1\n\n")
                        .replaceAll("(?i)<strong>(.*?)</strong>", "**$1**");
        System.out.println(md);
    }
}