How to Convert HTML to Markdown Cleanly
By Tools Star Hub Editorial Team · Published
Quick answer: open HTML to Markdown, paste up to 400,000 characters of HTML, and press Convert. Headings, paragraphs, bold and italic text, links, images, lists, blockquotes, code and tables become Markdown. Scripts, styles and embedded frames are removed with their content, comments are dropped, and other tags such as div and span disappear while their text is kept. Copy the result or download converted.md.
Markdown is easier to read, edit and version than HTML. Teams moving a help centre to a docs site, writers pulling a published post into a Markdown editor, and developers turning a web page into a README all need HTML turned into tidy Markdown without retyping it.
How are HTML tags converted?
Each supported tag maps to its usual Markdown form.
| HTML | Markdown |
|---|---|
| h1 to h6 | Lines starting with # to ###### |
| p | Text separated by a blank line |
| br | Two spaces and a line break |
| hr | --- |
| strong, b | **bold** |
| em, i | *italic* |
| code | `inline code` |
| pre | ``` fenced block |
| blockquote | > quoted lines |
| a | [text](href) |
| img |  |
| ul / ol | Items starting with - or 1. |
| table | Pipe table with a header row |
HTML entities such as &, < and are decoded into the characters they stand for, so the Markdown reads naturally.
What gets removed?
script, style, iframe, object, embed and noscript elements are skipped along with everything inside them, so tracking code, CSS and embedded players do not end up in your Markdown. HTML comments are dropped too.
Any other tag the converter does not map, such as div, span, section or article, is removed but its text is kept. Classes, IDs and inline styles disappear with the tags, which is usually what you want when moving to Markdown.
How are lists handled?
Unordered list items start with “- ”. Ordered list items all start with “1. ”, which Markdown renderers number automatically, so the output shows 1, 2, 3 when rendered. Nested lists are not indented, so sub-items appear at the same level as their parents. Re-indent them by hand if the hierarchy matters.
How are tables converted?
Tables become pipe tables. The row of th cells is used as the header, or the first row if there are no th cells, and a divider row is added below it. Cell text is kept but formatting inside cells, such as bold or links, is not, and merged cells are not represented. Very complex tables may need tidying after conversion.
What happens to links and images?
A link becomes [text](href) using the href exactly as written. A link with no href becomes [text](#). An image becomes  with its alt text, so missing alt text leaves the brackets empty, which is a good reminder to add descriptions for accessibility.
Relative URLs such as /blog/post or ../img/photo.png are kept as they are. If the Markdown will live somewhere else, use Find and Replace to turn them into full URLs.
Why does the spacing change?
Outside pre blocks, runs of spaces, tabs and line breaks are collapsed into single spaces, the same way a browser displays HTML. Indentation from your source file therefore does not carry over. Inside pre blocks whitespace is preserved, so code keeps its layout in the fenced block.
Where do I get the HTML from?
Most CMS editors have an HTML or code view you can copy from. In a browser you can view a page's source, or use the developer tools to copy just the element containing the article, which avoids menus and footers. Pasting only the main content gives the cleanest Markdown.
What should I check after converting?
Skim the result for nested lists that lost their indentation, tables that need tidying, and leftover text from navigation or buttons that were inside the HTML you copied. Render it with your Markdown tool, or convert it back with Markdown to HTML to compare.
Is my HTML uploaded?
No. The HTML is parsed and converted in your browser tab, so private pages and drafts stay on your device.
Why move content from HTML to Markdown?
Markdown files are plain text, so they work well with version control. Changes show up as readable line differences, reviews are easier, and the same file can be rendered by static site generators, documentation platforms and code hosting sites. Writers also find Markdown quicker to edit than HTML because there are no closing tags to manage.
Moving a knowledge base or a set of blog posts into Markdown also makes the content less tied to a particular CMS, since almost every publishing tool can import it.
How are headings and emphasis written?
An h1 becomes a single # followed by a space and the heading text, an h2 becomes ##, and so on down to ###### for h6. Bold text from strong or b tags is wrapped in double asterisks, and italic text from em or i tags in single asterisks. Inline code tags become backtick spans.
Because these are the most widely supported Markdown forms, the output renders consistently across common Markdown tools without needing extensions.
How are blockquotes and code blocks written?
Every line of a blockquote is prefixed with > and a space, so multi-line quotes stay together when rendered. A pre element becomes a fenced block with three backticks above and below, and its content keeps the original spacing, so indentation in code samples is preserved.
If the original HTML marked up a code block with a language class, add the language name after the opening backticks yourself to get syntax highlighting in your Markdown renderer.
How do I convert many pages from a CMS?
The tool handles one paste at a time, up to 400,000 characters, which is enough for a long article or several shorter ones pasted together. For a full site migration with hundreds of pages, a scripted export is more practical, but for a few dozen pages copying each article's HTML and converting it here is quick and lets you check each result as you go.
What should I do about images?
Image references keep their original src, so they still point at wherever the images are hosted. If you are moving to a new site, download the images, store them with your Markdown files, and update the paths. Find and Replace can change a whole folder path in one step, for example replacing an old uploads URL with a new relative folder.
Can I convert HTML emails?
You can, but email HTML is often built from nested layout tables, so the result may be a series of pipe tables rather than clean paragraphs. For newsletters, copy just the content area, or expect to remove table markup from the Markdown afterwards. Inline styles and tracking images in the email disappear or turn into plain image references.
How to convert HTML to Markdown
- Paste HTML. Add up to 400,000 characters, or press Example to see a sample.
- Convert. Press Convert to produce the Markdown.
- Tidy up. Fix nested lists, complex tables and any stray navigation text.
- Copy or download. Use Copy Markdown or download converted.md. Clear empties both boxes.
Example
A blog post
An article with an h2, two paragraphs, a bold phrase and a link becomes “## Heading”, two blank-line separated paragraphs, **bold** and [link](url).
A page with tracking code
Script and style blocks in the pasted HTML are removed entirely, leaving only the readable content.
A product table
A table with a th header row becomes a pipe table with the same columns, ready for a README.
Tips and limitations
Flat lists
Nested lists lose their indentation.
Plain cells
Formatting inside table cells is not kept.
URLs unchanged
Relative links stay relative.
Copy the content area
Paste the main article only for the cleanest result.
FAQ
- What happens to script and style tags?
- They are removed along with everything inside them, as are iframe, object, embed and noscript.
- Are div and span tags kept?
- No. The tags are dropped but their text stays in the Markdown.
- Why are all my numbered items 1.?
- Every ordered item is written as 1. and Markdown renderers number them automatically when displayed.
- Are nested lists indented?
- No. Sub-items appear at the same level as their parent items.
- Is bold text inside table cells kept?
- No. Cell text is kept but formatting inside cells is lost.
- What if a link has no href?
- It becomes [text](#).
- Are HTML entities decoded?
- Yes. Entities like & and become the characters they represent.
- Is whitespace in code blocks preserved?
- Yes. Inside pre blocks spacing is kept; elsewhere it is collapsed.
- Are HTML comments kept?
- No. Comments are dropped from the output.
- Can I convert a whole web page?
- Yes, but menus and footers come along as text. Copy just the main content for a cleaner result.
- How do I convert an HTML snippet into Markdown on this page?
- Paste the HTML, run convert, then copy the Markdown and spot-check headings, links, and lists.
- Will semantic tags like article or section become Markdown?
- They usually unwrap to their text and inner Markdown; there is no single Markdown twin for every HTML5 sectioning tag.
- How are images represented after conversion?
- img tags typically become Markdown image syntax with alt text and the src URL when both are present.
- What happens to inline styles and classes?
- Most converters drop class and style attributes because plain Markdown cannot express them.
- Can I keep a raw HTML table if Markdown tables look wrong?
- Some pipelines allow embedded HTML tables; otherwise simplify the table before converting.
- Why did my headings shift levels?
- Browsers and converters map h1–h6 to # through ######; nested section markup can look like a level jump.
- Are definition lists supported?
- Basic Markdown has no standard definition-list syntax; those tags may flatten to paragraphs.
- How do blockquotes convert?
- blockquote content usually becomes lines prefixed with > in Markdown.
- Will JavaScript-rendered HTML convert correctly?
- Only the HTML you paste is converted—copy the post-render DOM if the source page builds content with scripts.
- Is the HTML uploaded during conversion?
- Conversion is meant to run in the browser session; keep sensitive markup offline if needed.
Convert your page with the free HTML to Markdown tool.
Going the other way? Use Markdown to HTML.
Fix URLs in bulk with Find and Replace.