Markdown and HTML are two ways to describe the same thing: structured text. HTML was designed for browsers; Markdown was designed for humans. When you need to move content from the web into a writing environment, documentation system, or static site generator, converting HTML to Markdown is often the fastest path. Understanding how the conversion works — and where it breaks down — saves hours of manual cleanup.
What HTML-to-Markdown Conversion Actually Does
An HTML-to-Markdown converter reads an HTML document and maps each HTML element to its Markdown equivalent. The mapping is mostly straightforward: <h1> becomes # heading, <strong> becomes **bold**, <a href="url">text</a> becomes [text](url), <ul><li> becomes - list item, and <pre><code> becomes a fenced code block. The challenge is that HTML is far more expressive than Markdown — there are dozens of HTML elements that have no direct Markdown equivalent.
Elements like <div>, <span>, <table>, <form>, <iframe>, and CSS classes don't map cleanly to Markdown. Good converters handle tables by generating a GFM (GitHub Flavored Markdown) table, and handle unsupported elements by either dropping them or keeping them as raw HTML inside the Markdown file. For content that will be processed by a Markdown renderer that supports inline HTML, keeping complex elements as raw HTML is a valid approach.
The most widely used JavaScript library for this is Turndown, which powers many browser-based HTML-to-Markdown tools. Turndown is configurable: you can choose between ATX (#) and Setext (underline) heading styles, fenced (```) or indented code blocks, and - or * for bullet lists. For consistency with version control and diff readability, ATX headings and fenced code blocks are recommended.
Common Reasons to Convert HTML to Markdown
- Content migration: moving articles from a CMS like WordPress to a static site generator (Hugo, Astro, Jekyll) that uses Markdown files
- Documentation cleanup: extracting content from legacy HTML documentation to rebuild in a Markdown-based docs tool (GitBook, Docusaurus, VitePress)
- AI and LLM training data: Markdown is cleaner than HTML for language model fine-tuning because it removes tags and attributes that add noise without semantic value
- Personal knowledge bases: clipping web articles to Markdown for import into Obsidian, Logseq, or Notion
- Email templates: converting HTML email content to Markdown for editing before re-rendering as HTML
- Code review: reviewing generated HTML from a template engine by comparing the rendered Markdown version
What Gets Lost in the Conversion
Not everything in HTML survives the conversion to Markdown. Styling (colors, fonts, custom CSS classes) is lost entirely — Markdown has no concept of visual styling. Images are converted to  syntax but all sizing, alignment, and class attributes are dropped. Complex nested structures like multi-level nested lists, definition lists, and tables with merged cells either get simplified or converted to their closest Markdown approximation.
Metadata — HTML <head> content like <meta> tags, canonical URLs, and structured data — is not part of the visible content and is not converted. If you're migrating blog posts, you'll need to extract this metadata separately and add it as front matter (YAML or TOML) in the Markdown file. Most static site generators expect front matter for title, date, description, and tags.
Scripts and interactive elements have no Markdown equivalent and are dropped entirely. If you're converting a page with embedded forms, carousels, or dynamic content, the converted Markdown will only contain the static text and image content. This is usually desirable for documentation and content workflows, but it means the conversion is lossy for interactive pages.
HTML-to-Markdown conversion is a pragmatic tool for content portability. It works best on well-structured HTML — articles, documentation, blog posts, and reports. The output isn't always perfect, but it gets you 90% of the way to clean Markdown in seconds, leaving only targeted manual cleanup for edge cases. For developers managing content migrations, building documentation sites, or preparing data for language model training, an HTML-to-Markdown converter is an essential part of the toolkit.