HTML to Markdown

Why convert HTML to Markdown?

Markdown has become the standard plain-text format for technical writing, documentation, and developer-facing content. Unlike HTML, it reads naturally in raw form, works in any text editor, version-controls cleanly with Git, and is natively supported by platforms like GitHub, GitLab, Notion, Obsidian, and every major static site generator. When content already exists in HTML — from a CMS, a scraped article, an email, or a legacy documentation platform — converting it to Markdown unlocks all of these workflows without manual reformatting.

In 2026, there's an additional practical reason: AI and LLM pipelines strongly prefer Markdown over raw HTML. Research shows that clean Markdown reduces token usage by 68–87% compared to raw HTML for the same content. When feeding documentation into a retrieval-augmented generation (RAG) system, or preparing training data for a fine-tuned model, converting HTML to Markdown first is now standard practice. Perplexity, ChatGPT, and Gemini all internally convert web content to Markdown-like representations before processing — so giving them Markdown directly skips a lossy conversion step.

How DOM-based HTML to Markdown conversion works

Rather than applying fragile regular expressions to raw HTML strings — an approach that breaks on malformed tags, nested elements, and edge cases — this tool parses your HTML into a real DOM tree using the browser's built-in parser. It then walks each node recursively, mapping element types to their Markdown equivalents. Block elements (headings, paragraphs, lists, code blocks) get double newlines so the Markdown renders correctly. Inline elements (bold, italic, code, links) produce their Markdown syntax inline within the surrounding content.

This DOM-based approach is the same technique used by Turndown.js, the leading HTML-to-Markdown JavaScript library with over 2.5 million weekly npm downloads. It handles edge cases that regex-based converters miss: nested lists inside blockquotes, code inside list items, anchor tags wrapping images, and deeply nested table cells. Unknown structural HTML elements like div, section, and article simply pass through their children, so no content is silently dropped.

Common use cases: CMS migration, Notion, GitHub docs

CMS migration is the most common professional use case. Teams moving from WordPress, Confluence, SharePoint, or Ghost to a modern Markdown-based platform use HTML-to-Markdown conversion to process exported content. WordPress's export gives you HTML content blocks; Confluence exports pages as HTML or XHTML. Both convert cleanly. The Markdown files are then committed to a Git repository, imported into Notion via its Markdown import feature, or fed into a static site generator like Docusaurus, MkDocs, or Astro.

Personal knowledge management is another common use case. Tools like Obsidian and Logseq are built around Markdown files. When you find an article or documentation page you want to archive in your knowledge base, this converter lets you paste the page HTML and get a clean Markdown file in seconds — preserving structure without the noise of raw HTML tags. The word count display helps confirm no content was dropped during conversion.

Pandoc vs browser-based converters: when to use which

Pandoc is the gold standard for document conversion in professional pipelines — a command-line tool that converts between dozens of formats including HTML to Markdown, Markdown to PDF, and many others. It handles edge cases like definition lists, footnotes, and complex nested structures, and supports more output flavors than any JavaScript converter: MultiMarkdown, Pandoc Markdown, AsciiDoc, reStructuredText, and more. If you're building an automated batch-conversion pipeline on a server, Pandoc is the right choice.

For one-off conversions, quick content migrations, or work with sensitive material that shouldn't leave your device, a browser-based converter is faster and more practical. Nothing to install, no command line to learn, instant results. This tool covers the vast majority of real-world HTML structures — headings, paragraphs, lists, tables, code blocks, links, images — making it the practical choice for everyday HTML-to-Markdown needs. Markdownify and h2m are solid npm alternatives if you need to script conversions in Node, but they require a project setup that this tool skips entirely.

Markdown syntax reference and output compatibility

Key Markdown conventions this tool follows: headings use # through ###### for h1–h6, bold wraps text in **double asterisks**, italic in *single asterisks*, inline code in backticks, and fenced code blocks in triple backticks with an optional language identifier. Links follow the pattern [text](url) and images use . Unordered lists use a dash prefix; ordered lists use numbers followed by a period. Blockquotes prefix each line with >.

Tables use pipe characters to separate columns, with a separator row of dashes (and optional colons for alignment) after the header row. Strikethrough wraps text in ~~double tildes~~. The output follows CommonMark with GitHub Flavored Markdown (GFM) extensions, making it compatible with GitHub, GitLab, VS Code preview, Notion, Obsidian, and virtually every modern Markdown renderer. If you see rendering differences between platforms, they're almost always due to the platform using a non-standard Markdown flavor rather than an issue with the output.

Privacy, no limits, and mobile support

This HTML to Markdown converter runs 100% in your browser. Nothing is uploaded to a server, nothing is logged, and no account is needed. That means it's safe to paste confidential documentation, internal wikis, or client content — it never leaves your device. You can even disconnect from the internet after the page loads and it keeps working, which is the simplest proof that no server is involved.

There's no file size limit, no daily conversion quota, and no paywall. Online converters that process files server-side, like some Pandoc web wrappers or document conversion APIs, often cap file sizes at 1–5 MB or limit free users to a few conversions per day. This tool has none of those restrictions. It also works on iPhone and Android — paste HTML from your phone's browser, convert it, and copy the Markdown result directly into Notion, Obsidian, or any other app.

HTML-to-Markdown is a lossy conversion — what that means in practice

It is easy to assume that converting between two document formats is a reversible process, but HTML-to-Markdown conversion is fundamentally lossy. HTML is a superset of what Markdown can express. A <span style="color: red"> element has no Markdown equivalent — the text survives the conversion but the colour instruction is silently dropped. A <table> with merged cells (colspan or rowspan) can be approximated as a GFM pipe table at best, but the merge semantics disappear entirely. Any element whose meaning lives in a CSS class, an inline style, or a non-standard attribute — tooltips, ARIA labels, data attributes — simply does not exist in Markdown's vocabulary and is discarded during traversal. This is a deliberate design choice, not a bug: Markdown was designed to represent prose structure, not visual layout.

The inverse direction — Markdown-to-HTML — is completely lossless within the spec. Every valid Markdown construct has a precisely defined HTML output: a # heading always becomes <h1>, **text** always becomes <strong>text</strong>, a fenced code block always becomes <pre><code>. This asymmetry matters when you are choosing a workflow. Converting HTML to Markdown and then back to HTML does not round-trip to the original; it produces a semantically simplified version. That simplified version is often exactly what you want — clean, portable, readable prose — but you should not treat it as a faithful replica of the source. Always keep the original HTML if lossless archiving is the goal.

There is also the whitespace normalization problem. HTML collapses all whitespace: dozens of newlines and spaces in the source render as a single space character in the browser. Markdown, by contrast, is whitespace-sensitive: two trailing spaces mean a hard line break, a blank line means a paragraph boundary. A DOM-based converter infers paragraph structure from block-level elements — <p>, <div>, <br>, <li> — rather than from the raw whitespace in the HTML source, which is the only reliable way to reconstruct the intended document flow. Regex-based converters that work on raw text rather than a parsed DOM frequently collapse or multiply blank lines because they have no model of block boundaries.

Why HTML-to-Markdown conversion is essential in modern workflows

Content migration is the use case that drives most production usage. Moving a large WordPress installation or a Confluence wiki to a Markdown-based platform — Hugo, Astro, Docusaurus, MkDocs — means converting thousands of HTML posts to Markdown files. Automation tools like wordpress-export-to-markdown and WPXML-to-Markdown parse the WordPress export XML, extract the HTML content field for each post, run it through a converter such as Turndown.js, and write the result to .md files. Teams doing Confluence migrations use a similar pipeline: export the space as HTML, iterate over the exported files, and pipe each through a converter. The quality of the Markdown output determines how much manual cleanup is required afterward, so choosing a DOM-based converter over a regex-based one pays dividends at scale.

AI and LLM context preparation has become equally important. Web pages fed to language models as raw HTML waste a significant fraction of the available context window on tag noise. A paragraph inside a <div class="article-body"> with a dozen nested wrapper elements costs far more tokens than the same paragraph in plain Markdown. Tools like Jina Reader (r.jina.ai), Firecrawl, and Trafilatura have built their entire value proposition around converting arbitrary web pages to clean Markdown before delivering them to an AI pipeline. Research published in 2024 quantified the difference: Markdown reduces token usage by 68–87% compared to raw HTML for equivalent content, which directly reduces API cost and increases the effective context available for reasoning. For retrieval-augmented generation (RAG) pipelines that chunk and embed web content, clean Markdown also produces more semantically coherent chunks because paragraph and heading boundaries in Markdown map directly to meaningful document structure, rather than to arbitrary div nesting.

Documentation modernization is a third wave of adoption. Legacy enterprise documentation living in Confluence, SharePoint, or old static HTML sites is increasingly being migrated to developer-friendly systems: Notion for non-technical teams, Obsidian for personal knowledge management, or a Git repository for engineering docs. HTML-to-Markdown conversion is the linchpin of that migration. Rich HTML emails present a related use case: converting a formatted email thread to Markdown lets you include it as a ticket comment, a meeting note, or a wiki entry without the visual clutter of raw HTML tags or the opaque base-64 blobs that raw email sources contain. In each of these contexts the converter is not the end product — it is the translation layer that unlocks a downstream workflow.

Turndown.js, Pandoc, and the HTML-to-Markdown library landscape

Turndown.js is the dominant JavaScript library for HTML-to-Markdown conversion, with more than 2.5 million weekly npm downloads and over 10,800 GitHub stars as of 2026. It works by building a DOM tree from the input HTML and walking each node to emit a Markdown equivalent. Its behaviour is highly configurable: headingStyle controls whether headings use ATX style (# Heading) or Setext style (Heading =======), bulletListMarker sets whether unordered list items use -, *, or +, codeBlockStyle switches between fenced triple-backtick blocks and four-space-indented blocks, and linkStyle chooses between inline links ([text](url)) and reference-style links collected at the bottom of the document. Plugins extend Turndown with additional rules — strikethrough, tables (via the turndown-plugin-gfm package), task lists — keeping the core small while supporting the full GFM feature set when needed. The same DOM-traversal architecture that makes Turndown reliable in a Node environment is what makes a browser-based converter reliable: the browser's own HTML parser, which handles malformed and real-world HTML far better than any hand-written parser, does the heavy lifting.

Pandoc, written in Haskell by John MacFarlane, is the gold standard for document format conversion at the academic and professional level. It converts between more than 40 formats: HTML to Markdown, Word (.docx) to Markdown, LaTeX to HTML, Markdown to PDF, EPUB, and dozens more. Its extended Markdown dialect supports footnotes, definition lists, citation syntax, and LaTeX math blocks — features that are out of scope for CommonMark or GFM. For converting HTML documents that contain academic citations, chemical formulae, or cross-referenced footnotes, Pandoc has no peer. The trade-off is operational: Pandoc requires installation, a Haskell runtime, and command-line usage. It is the right tool for a server-side batch conversion pipeline, not for quick ad-hoc work in a browser.

The Python ecosystem has html2text, originally written by Aaron Swartz and later maintained by the open-source community. It is a simple, dependency-light library that converts HTML to Markdown-formatted text and is widely used in Python scraping and content-processing scripts. It produces readable output for standard prose but handles edge cases such as nested lists, complex tables, and code blocks less gracefully than Turndown or Pandoc. A critical distinction separates all three of these libraries from tools that merely strip HTML tags: strip_tags() in PHP or element.innerText in JavaScript discard all formatting and return flat plain text — no headings, no emphasis, no lists, no links. A proper HTML-to-Markdown converter preserves all of that structure, encoding it in Markdown syntax rather than HTML tags. The distinction matters enormously when the output will be rendered in a Markdown-aware environment: stripping tags produces an undifferentiated wall of text, while a real converter produces a document whose hierarchy is immediately readable and renderable.