How to Convert HTML to Clean Markdown for Docs and Issues

Why convert HTML to Markdown?

You copy a nicely formatted snippet from a web page, paste it into a GitHub issue or a README, and suddenly you are staring at a wall of <div> tags and inline styles. Markdown is the lingua franca of docs, wikis, chat and issue trackers, but most of the content we run into lives as HTML. Rewriting it by hand — turning every <strong> into ** and every <li> into a dash — is tedious and easy to get wrong.

An HTML-to-Markdown converter automates that translation and hands you clean, portable text that renders correctly wherever Markdown is supported. It is especially handy for migrating a CMS export, cleaning up scraped content, or turning a rich email into a plain note.

How the conversion works

Under the hood, the converter parses your HTML into a DOM tree and walks each node, mapping elements to their Markdown equivalents. The rules are small and predictable:

• Block elements like <h1>–<h6>, <p> and <blockquote> become headings, paragraphs and > quotes separated by blank lines.
• Inline elements such as <strong>, <em> and <code> wrap text in **, * and backticks.
• Lists map <ul> and <ol> to - and 1. markers, preserving nesting through indentation.
• Links and images turn <a href> and <img> into [text](url) and ![alt](src).

Anything without a Markdown counterpart — styling spans, tracking attributes, empty wrappers — is stripped so only the meaningful content survives.

A practical walkthrough

Suppose you grabbed this markup from a documentation page:

<h2>Install</h2>
<p>Run <code>npm install</code> then read the <a href="https://example.com/docs">docs</a>.</p>
<ul>
  <li><strong>Fast</strong> startup</li>
  <li>Zero config</li>
</ul>

Paste it in and you get tidy, ready-to-commit Markdown:

## Install

Run `npm install` then read the [docs](https://example.com/docs).

- **Fast** startup
- Zero config

Everything runs locally in your browser — nothing is uploaded — so you can safely convert internal docs or proprietary content. Paste your markup into the HTML to Markdown tool and copy the result.

Common pitfalls and tips

• Tables: Simple HTML tables convert to GitHub-flavored pipe tables, but tables with merged cells (colspan/rowspan) have no Markdown equivalent and will flatten. Simplify the structure before converting.
• Whitespace: HTML collapses runs of whitespace, while Markdown treats blank lines as meaningful. Stray newlines inside a <p> are normalized so paragraphs stay intact.
• Scripts and styles: <script> and <style> blocks hold no readable content, so they are removed rather than escaped into the output.
• Special characters: Literal *, _ or # in your text get backslash-escaped so they do not accidentally trigger Markdown formatting.
• Round-tripping: To go the other direction, reach for Markdown to HTML, or refine the result live in the Markdown Editor.

Conclusion

Converting HTML to Markdown turns messy, tag-heavy content into clean text you can drop into any doc, issue or note. Once you understand the block-versus-inline mapping, you can predict the output and quickly spot the edge cases — complex tables, custom HTML and inline styles — that still deserve a manual touch. For everything else, a quick paste-and-copy saves real time and keeps your documentation consistent.