HTML to Markdown: Convert HTML to Clean Markdown Text Online
Convert HTML markup to clean, readable Markdown syntax. Ideal for migrating web content to Markdown-based CMSs, wikis, and documentation tools.
Try the free online tool
Runs entirely in your browser — no signup, no uploads.
HTML to Markdown conversion is the reverse problem: you have HTML content — perhaps scraped from a website, exported from a CMS, or copied from a web page — and you need it in clean, readable Markdown format for use in a Markdown-based documentation system, static site generator, or GitHub repository. Manually converting HTML tags to Markdown syntax is tedious and error-prone.
This HTML to Markdown Converter parses HTML markup and produces well-formatted Markdown that preserves the document's structure: headings become pound signs, bold text becomes double asterisks, lists become hyphens, links retain their URLs, and code blocks are wrapped in backticks. Unwanted HTML attributes, inline styles, and script tags are stripped to produce clean output.
The tool is particularly valuable for content migrations — moving content from an old CMS (which stores HTML) to a new Markdown-based platform. It handles nested structures, complex tables, and deeply indented lists that would take hours to convert by hand. This guide explains which HTML elements are supported and how to handle edge cases.
What Does HTML to Markdown Conversion Involve?
Converting HTML to Markdown is more complex than the reverse because HTML has far more expressive power than Markdown. HTML can describe pixel-perfect layouts, apply inline styles, embed scripts, and define complex table structures. Markdown intentionally cannot express most of this — it is a simplified writing format focused on semantic content structure.
A well-designed HTML to Markdown converter identifies semantic HTML elements (<h1>-<h6>, <p>, <ul>, <ol>, <li>, <a>, <strong>, <em>, <code>, <pre>, <blockquote>, <table>) and maps them to their Markdown equivalents. Presentational elements (like <span style='color: red'>) that have no Markdown equivalent are stripped, preserving the text content but discarding the styling.
The quality of the output depends heavily on the quality of the input HTML. Well-structured semantic HTML produces clean Markdown. Tag-soup HTML full of inline styles and presentational divs produces Markdown that may need manual cleanup.
How to Use This Tool
Converting HTML to Markdown takes just a few steps:
- 1
Paste your HTML
Paste the HTML code you want to convert into the left input panel. This can be a complete HTML document or just a fragment — the converter handles both.
- 2
Configure conversion options
Choose your heading style (ATX-style with # signs is recommended), bullet list style (hyphen, asterisk, or plus), and whether to preserve links or convert them to plain text.
- 3
Review the Markdown output
The right panel shows the generated Markdown. Check that headings, lists, tables, and links have been converted correctly. Complex nested HTML may require minor manual adjustments.
- 4
Handle unsupported elements
HTML elements that have no Markdown equivalent (like <div> with classes, <table> with complex spanning cells, or <figure>) may be partially or fully stripped. Review these sections and manually add any important content.
- 5
Copy the Markdown
Click 'Copy Markdown' to copy the result to your clipboard, ready to paste into your documentation tool, CMS, or Git repository.
Common Use Cases
HTML to Markdown conversion is a key step in many content workflows:
- CMS migration: convert HTML content from WordPress, Drupal, or other HTML-based CMS platforms to Markdown for migration to a headless CMS or static site generator.
- Documentation generation: convert API documentation or help center articles exported as HTML into Markdown for a docs-as-code workflow.
- Web content archiving: capture web page content as clean Markdown for inclusion in a knowledge base or personal notes system.
- GitHub wiki population: convert existing HTML documentation pages to Markdown format for GitHub Wikis or README files.
- Email to documentation: convert HTML emails containing technical instructions into Markdown documentation.
Tips and Best Practices
Get the cleanest Markdown output from HTML with these tips:
- Clean up HTML before converting: remove unnecessary <div> wrappers, inline styles, and JavaScript before pasting HTML. The cleaner the input, the cleaner the Markdown output.
- Use semantic HTML as the source: ensure the HTML uses semantic tags (<h1>-<h6>, <strong>, <em>, <ul>, <ol>) rather than styling divs and spans. Semantic HTML maps cleanly to Markdown equivalents.
- Review table conversions manually: complex HTML tables with merged cells, colspan, and rowspan attributes cannot be represented in standard Markdown. The converter will do its best, but manual cleanup is often needed.
- Check link URLs: the converter preserves <a href> link URLs in Markdown link syntax. Verify that relative URLs are updated to absolute URLs if you are moving content to a different domain.
- Post-process with a linter: run the output through a Markdown linter (like markdownlint) to catch formatting inconsistencies introduced during conversion.
Frequently Asked Questions
What HTML elements can be converted to Markdown?
The converter handles the standard semantic HTML elements: headings (<h1>-<h6>), paragraphs (<p>), bold (<strong>, <b>), italic (<em>, <i>), links (<a>), images (<img>), ordered and unordered lists (<ol>, <ul>, <li>), blockquotes (<blockquote>), inline code (<code>), and preformatted code blocks (<pre>).
What happens to HTML elements that have no Markdown equivalent?
Elements with no Markdown equivalent are handled in two ways: the element's text content is preserved but its tags are stripped (for inline elements like <span>), or the element is either kept as raw HTML or removed entirely (for structural elements like <div>). You can configure whether to keep unsupported HTML as raw HTML in the output.
Can the tool convert HTML tables to Markdown tables?
Yes, for simple tables without merged cells. HTML <table> with <th> and <td> cells is converted to GFM (GitHub Flavored Markdown) pipe table syntax. Complex tables with colspan or rowspan cannot be represented in Markdown and will require manual restructuring.
Does the converter strip inline CSS styles?
Yes. Inline styles (<span style='...'>) are stripped because Markdown has no equivalent for arbitrary CSS. The text content is preserved, but formatting applied purely through CSS (like color or font size) is lost.
Can I convert a whole web page's HTML to Markdown?
Yes, but the results will include the page's navigation, header, footer, and other structural elements in addition to the main content. For best results, copy only the main content section of the page's HTML rather than the full page source.
How are HTML entities handled in the conversion?
HTML entities like &, <, >, and are decoded to their character equivalents during conversion. Non-breaking spaces ( ) become regular spaces, and HTML-encoded characters become their literal Unicode representations.
Is the conversion reversible?
Converting HTML to Markdown and back to HTML is approximately reversible for standard content. However, any HTML attributes, styles, or elements that were stripped during the HTML-to-Markdown step will not reappear when converting the Markdown back to HTML.
Ready to use this tool?
Free, instant, no account required. Runs entirely in your browser.