HTML to Markdown: Clean Up Markup for Documentation
Markdown is the preferred format for README files, wikis, pull request descriptions, and static site generators. This converter strips HTML's verbose syntax and produces clean, readable Markdown — handling all common block and inline elements correctly.
Supported HTML Elements
Block elements: h1–h6 (# through ######), p (paragraph), ul/ol/li (unordered and ordered lists), blockquote (> prefix), pre/code (fenced code block), hr (--- rule). Inline elements: strong/b (bold **), em/i (italic *), a (links [text](url)), img (images ), code (inline `backtick`). Unsupported tags are stripped but their text content is preserved.
Entity Decoding
HTML entities in the source — &, <, >, ", ', — are decoded to their character equivalents in the Markdown output. This means pasted HTML from a rendered page produces clean readable Markdown rather than entity-encoded text.
Why Regex Instead of DOMParser
This converter uses pattern matching rather than DOM parsing so it works both on the server (for SSR/hydration consistency) and in the browser. The trade-off is that deeply nested or malformed HTML may not convert perfectly. For simple blog posts, README content, and documentation, the regex approach covers the vast majority of real-world markup.
Practical Examples
Migrating a Blog Post to a Markdown Wiki
Convert a CMS article's HTML export to a Markdown wiki page.
- 1.Paste the HTML source of the article
- 2.Review the Markdown output — headings, paragraphs, links should convert correctly
- 3.Copy the Markdown
- 4.Paste into your wiki page or .md file and make minor manual adjustments for any edge cases
Converted Elements
- h1–h6 → # through ######
- strong/b → **bold**, em/i → *italic*
- a href → [text](url), img → 
- ul/ol/li → -, 1. lists; blockquote → > prefix; pre/code → ``` fenced blocks
Good Use Cases
- Migrating blog posts or CMS content to Markdown wikis
- Converting email HTML to Markdown for documentation
- Preparing web page snippets for GitHub README files
- Cleaning up copied browser HTML for static site generators
Frequently Asked Questions
Which HTML elements are supported?
Headings (h1–h6), paragraphs, strong/b, em/i, a (links), img, code, pre/code blocks, ul/ol/li lists, blockquotes, and hr. Unsupported tags are stripped, leaving their text content.
What happens to inline styles and CSS classes?
Inline styles and class attributes are ignored. Only semantic HTML structure is converted to Markdown — presentation-only markup is stripped.
Are HTML entities decoded?
Yes. Common HTML entities (&, <, >, ", ', ) are decoded to their character equivalents in the Markdown output.