HTML to Markdown Converter

How to convert HTML to Markdown

1. Paste any HTML fragment — a blog post, a div block, or a full document body — into the input field on the left.
2. Click "Convert" — the clean Markdown output appears instantly in the right panel.
3. Switch to "Markdown → HTML" using the toggle above the fields if you need the reverse direction.
4. Click "Copy" to copy the output to your clipboard, or "Download .md" to save the file locally.
5. Paste the Markdown directly into your static site generator, documentation tool, or GitHub README.

How the HTML to Markdown converter works

The converter runs entirely in your browser using Turndown, a JavaScript library that traverses the parsed HTML DOM tree and maps each element to its Markdown equivalent. When you click Convert, the input string is parsed into a document fragment, then each node — headings, paragraphs, lists, code blocks, links, images — is walked recursively and replaced with the corresponding Markdown syntax. The result is written directly to the output field without any network request. Your content never leaves your machine.

Turndown follows a ruleset system: each HTML element has a filter that matches it and a replacement function that produces Markdown. For elements outside the supported set — div, span, custom attributes, inline styles — the default rule strips the tag and keeps only the text content. This produces clean, portable Markdown without residual HTML noise.

// Turndown runs this logic in your browser — no server involved:
import TurndownService from 'turndown'

const td = new TurndownService({
  headingStyle: 'atx',       // # H1, ## H2  (not underline style)
  bulletListMarker: '-',     // - item        (not * or +)
  codeBlockStyle: 'fenced',  // ```code```  (not indented)
})

const html = '<h1>Hello</h1><p>A <strong>bold</strong> word.</p>'
const markdown = td.turndown(html)
// Output:
// # Hello
//
// A **bold** word.

Who uses HTML to Markdown conversion

Markdown is the native input format for static site generators (Hugo, Jekyll, Astro, Eleventy), documentation platforms (Docusaurus, MkDocs, GitBook), and developer collaboration tools (GitHub, GitLab, Notion). If your content currently lives as HTML — in a CMS, a legacy site, an email template, or a scraped web page — converting it to Markdown is the fastest route to reuse.

• Static site migration — converting WordPress or Drupal post bodies to Markdown for Hugo, Astro, or Jekyll.
• Documentation rebuild — transforming Confluence or legacy HTML docs into MkDocs or Docusaurus source files.
• README and wiki creation — cleaning up copied web content into a readable GitHub README.
• Email to documentation — converting HTML email templates into plain, editable Markdown records.
• CMS export cleanup — post-processing HTML exports from headless CMS platforms into portable Markdown.
• Developer tooling — preprocessing HTML scraped from web pages before feeding it to Markdown-first editors or LLMs.

HTML elements and their Markdown output

Markdown covers the most common block and inline elements. The table below shows exactly what the converter produces for each HTML tag. Elements not in this set — div, span, section, article, aside, data attributes, inline styles — are stripped to their text content only.

When to convert to Markdown — and when not to

Convert to Markdown when:

• Target platform is Markdown-native — static site generators, GitHub READMEs, Notion, Obsidian, Bear, Typora.
• Version control matters — Markdown diffs cleanly in git; HTML tags create visual noise in pull request reviews.
• Non-developer editors — writers find Markdown syntax easier to read and write than raw HTML tags.
• Content portability — Markdown is a long-lived plain-text format with no vendor lock-in.
• Documentation pipelines — tools like Docusaurus, MkDocs, and VitePress use Markdown as their primary source format.

Keep HTML when:

• Precise layout is required — multi-column grids, absolute positioning, complex CSS class structures.
• Interactive elements are embedded — forms, custom widgets, iframes, JavaScript components inside the content.
• The target renders HTML directly — email clients, legacy CMS systems, platforms that do not process Markdown.
• Complex nested tables — Markdown tables have no merged cells, rowspan, or colspan support.
• Custom attributes matter — data-*, aria-*, and class values are stripped during conversion.

Conversion edge cases and what to expect

HTML is a superset of what Markdown can express, so some information is always lost in conversion. Understanding these edge cases helps you decide when post-processing is needed and prevents surprises in the output.

• Inline styles are stripped — <p style="color:red"> becomes a plain paragraph. CSS formatting has no Markdown equivalent.
• Class and id attributes are dropped — <div class="highlight"> loses its class. If you rely on these for client-side JavaScript, conversion is not appropriate.
• Nested block elements — a <div> wrapping a <p> is unwrapped; the paragraph text is preserved, the div discarded.
• Image dimensions — <img width="800"> loses its size attributes. Only src and alt are preserved in the output.
• Script and style tags — completely stripped including all their content. Run conversion on content HTML only, not full pages.

// Input HTML (with class, style, and wrapper div):
<div class="post" style="padding: 20px">
  <h2 id="title">Developer Guide</h2>
  <p>A <strong>bold</strong> and <em>italic</em> sentence.</p>
  <ul>
    <li>First item</li>
    <li>Second item</li>
  </ul>
</div>

// After HTML → Markdown conversion:
// ## Developer Guide
//
// A **bold** and *italic* sentence.
//
// - First item
// - Second item
//
// Note: class, id, inline style, and <div> wrapper are removed.
// Text content and semantic structure are fully preserved.