How to Convert HTML to Clean Markdown

What HTML becomes in Markdown

Common semantic HTML has a direct Markdown equivalent. An h2 becomes a level-two heading, strong and em become emphasis, anchors become links, and ordered or unordered lists retain their hierarchy. Decorative containers such as div and span usually disappear while their text remains.

• h1–h6 → Markdown heading levels
• strong and em → bold and italic emphasis
• a href → Markdown links
• ul, ol, and li → bulleted or numbered lists
• blockquote → quoted text
• pre and code → fenced or inline code
• table elements → Markdown table syntax when the structure is compatible

<h2>Release notes</h2>
<p>Read the <a href="/guide">guide</a>.</p>
<ul><li>Faster export</li><li>Cleaner tables</li></ul>

## Release notes

Read the [guide](/guide).

- Faster export
- Cleaner tables

How to convert HTML to Markdown online

Use source HTML when possible. Copying the visible text of a page loses link destinations and structural information before conversion even begins.

1. Paste or open the HTMLAdd a complete HTML fragment, open an .html file, or paste markup copied from a CMS source view.
2. Review the Markdown outputCheck the heading outline, links, nested lists, tables, images, and code blocks.
3. Remove page-specific leftoversDelete navigation labels, repeated footer content, tracking links, or promotional blocks that were part of the page rather than the article.
4. Copy or download MarkdownCopy the cleaned result or download an .md file for your editor, repository, documentation site, or note app.

Clean HTML before a CMS migration

A migration is easier when content is separated from the old site theme. Convert the article body rather than the entire page shell, then standardize heading levels and link destinations. Relative URLs such as /about may need to become full URLs if the Markdown will live on another domain.

Check image sources as well. A path that worked inside the old CMS may break in a repository or new publishing system. Record the original asset URL or move the image before retiring the old site.

Why some HTML does not map perfectly

Markdown intentionally has fewer layout controls than HTML. Multi-column layouts, tabs, accordions, forms, embedded widgets, and complex tables do not have universal Markdown syntax. A converter should preserve the readable content and simplify unsupported presentation.

The converter turns a simple row-and-column table into Markdown table syntax. If it finds merged cells created with rowspan or colspan, it keeps the sanitized table HTML instead of inventing a lossy Markdown layout. For portable Markdown, rewrite that fragment as headings, lists, or a simpler table.

Review the result as content, not code

A technically valid conversion can still contain a weak outline, vague link text, or duplicate navigation labels. Read the Markdown preview from top to bottom, confirm that headings describe the page accurately, and remove anything readers do not need. That editorial pass is what turns scraped markup into maintainable content.