Why convert HTML to Markdown?
Markdown is significantly easier to read, write, and maintain than HTML. Where HTML uses verbose tags like <h2>Title</h2>, Markdown uses ## Title. The same content takes less space, is easier to diff in version control, and can be read by a human without rendering it first.
- CMS migration — move content from a database-driven site to a static site generator like Next.js, Astro, or Hugo
- Copy from web pages — paste HTML from a browser and get clean Markdown for Notion, GitHub, or Obsidian
- Documentation — convert legacy HTML docs to Markdown for modern doc platforms
- Email to content — strip email HTML boilerplate and extract the readable content
What gets converted
- Headings — h1–h6 → # through ######
- Formatting — strong/b → **bold**, em/i → *italic*
- Links — <a href="..."> → [text](url)
- Lists — ul/ol/li → - item or 1. item
- Code — <code> → `backticks`, <pre> → fenced code blocks
- Blockquotes — <blockquote> → > quote
- Tables — <table> → pipe-separated Markdown table
- Dividers — <hr> → ---
Limitations
HTML is more expressive than Markdown — some things have no direct equivalent. Inline styles, CSS classes, custom attributes, and complex nested layouts will either be stripped or left as raw HTML inline (which is valid in most Markdown parsers). For best results, convert semantic HTML — avoid divs used purely for layout.