What Is an HTML to Markdown Converter?
An HTML to Markdown converter takes HTML markup (the angle-bracket tags that structure web pages) and rewrites it as Markdown, the plain-text format created by John Gruber in 2004. Markdown is readable as-is and converts back to HTML. Going the other way, from HTML to Markdown, is how you move content out of web pages, CMS exports and rich-text editors into READMEs, wikis, static site generators and note apps.
This tool parses your HTML with the browser’s built-in DOMParser, walks the document tree and writes Markdown that follows CommonMark plus the GitHub Flavored Markdown (GFM) extensions for tables, strikethrough and task lists. No library is downloaded and nothing is uploaded. The conversion is instant.
The hard part isn’t mapping <strong> to **. It’s making sure the Markdown renders back to the same document. That means escaping text that looks like syntax, keeping spaces where the browser showed them, and knowing when Markdown can’t express something. Most of this page covers those details.
How to Convert HTML to Markdown
- Paste your HTML into the input area. A full page or a fragment both work.
- Click Convert or press
Ctrl+Enter. - Copy the Markdown with the Copy button or
Ctrl+Shift+C.Ctrl+Lclears both panes.
The settings below the buttons control the output style. Changing one while a result is showing converts again straight away:
- Headings: ATX (
# Title) or Setext, which underlines levels 1 and 2 with===and---. Levels 3 to 6 are always ATX. - Bold / Italic:
**or__, and*or_. - Bullet:
-,*or+for unordered lists. - Line break: how
<br>is written. Two trailing spaces work in every Markdown flavor but are invisible and easy to strip by accident. A trailing backslash is explicit, but the original Markdown.pl doesn’t support it. - Keep HTML Markdown can’t express: see the section on HTML with no Markdown equivalent below.
How Each HTML Element Is Converted
| HTML | Markdown | Notes |
|---|---|---|
<h1>–<h6> | # … ###### | A trailing # in the text is escaped so it isn’t read as a closing sequence |
<p>, <div>, <section> | Paragraphs separated by a blank line | Text directly inside a <div> becomes a paragraph too |
<strong>, <b> / <em>, <i> | **bold** / *italic* | Spaces at the edges move outside the markers |
<del>, <s> | ~~strike~~ | GFM |
<a href> | [text](url "title") | <https://…> autolink when the text equals the URL |
<img> |  | Uses data-src when lazy-loaded images have no src |
<ul>, <ol start="5"> | - item, 5. item | Nesting is indented by the marker width |
<input type="checkbox"> in <li> | - [x] done | GFM task list |
<pre><code class="language-js"> | Fenced block with js | The fence grows if the code contains backticks |
<code> | `code` | Content with backticks gets a longer fence |
<blockquote> | > quote | Every line is prefixed, blank lines become > |
<table> | GFM pipe table | Alignment from align or text-align |
<hr> | --- | |
<sub>, <sup>, <kbd>, <mark>, <u> | Kept as HTML | Or plain text with Keep HTML off |
<details> / <summary> | Kept as HTML, body in Markdown | Collapsible sections on GitHub |
<dl> | Term paragraph + definition paragraph | CommonMark has no definition lists |
Why Escaping Matters
Markdown gives meaning to ordinary characters, so text copied from HTML can turn into formatting when it’s rendered. Each of these paragraphs is plain text in HTML:
<p>1986. A great year for music.</p>
<p># is called a hash sign.</p>
<p>Use *args to collect positional arguments.</p>
<p>The <script> tag runs JavaScript.</p>
Written out verbatim, the first becomes a numbered list starting at 1986, the second a heading, and the third italicizes half the sentence. The fourth is the dangerous one. The browser decodes <script> to the text <script>, and if that text goes into Markdown unescaped, the Markdown renderer emits a real <script> tag. The converter writes:
1986\. A great year for music.
\# is called a hash sign.
Use \*args to collect positional arguments.
The \<script> tag runs JavaScript.
Escaping is context-aware so the output stays readable. Characters that only matter at the start of a line (#, >, -, +, 1.) are escaped only there. A < is escaped only when a letter or / follows, an & only when it would form an entity like &, and an _ only where it could actually start emphasis. So snake_case_name stays clean, while _private becomes \_private.
Whitespace and Emphasis: the WYSIWYG Problem
Rich-text editors such as TinyMCE, CKEditor, Google Docs and Notion often put the space inside the formatting tag: <strong>Note: </strong>text or see<a href="/docs"> the docs</a>. A converter that trims each element’s content writes **Note:**text and see[the docs](/docs), so the space the reader saw is gone. This tool collapses whitespace the way the browser does, then moves leading and trailing spaces outside the markers: **Note:** text, see [the docs](/docs).
There’s a second trap. CommonMark only lets ** and * open and close emphasis in certain positions (the “left-flanking” and “right-flanking” rules). In <strong>Note:</strong>text, the closing ** would sit between a colon and a letter, so Markdown prints the asterisks literally. The same happens with _ in the middle of a word (foo_bar_baz is never italic). The converter checks those rules for every bold, italic and strikethrough span. If the preferred marker can’t work, it tries the other one (** ↔ __, * ↔ _), and as a last resort keeps <strong> or <em>. Nested bold and italic get different marker characters (**_both_**) so the delimiter runs can’t merge.
Tables, Code Blocks and Lists in Detail
Tables. GFM pipe tables need a header row, so the first row becomes the header. Column alignment comes from align="right" or style="text-align: center" and is written as ---: or :---:. Pipes in cell text are escaped as \|, even inside code. Multi-paragraph cells and <br> become <br> (a space with Keep HTML off), because a newline would end the row. Pipe tables can’t express merged cells, lists, code blocks or nested tables. If a table has any of those, the whole table is kept as clean HTML (with Keep HTML on) instead of being silently broken.
Code blocks. The fence is always one backtick longer than the longest backtick run in the code, so a code sample that contains a code fence can’t close the block early. The language comes from language-* or lang-* classes, as used by Prism, highlight.js and Hugo’s Chroma, and names like c++ are kept whole. Syntax-highlighting <span> wrappers are ignored, and <br> inside <pre> becomes a newline.
Lists. Nested lists are indented by the width of the parent marker, which is what CommonMark requires (3 spaces under 1., 4 under 10.). <ol start="5"> keeps its number. The old <ul><li>a</li><ul>…</ul></ul> nesting is attached to the item above it. Two lists of the same type in a row are separated by an empty HTML comment, because without it Markdown would merge them into one list.
HTML That Has No Markdown Equivalent
Markdown is deliberately small. These parts of HTML don’t survive a pure-Markdown conversion:
- Styling: inline
style,class,<font>, colors and alignment of paragraphs are dropped. - Subscript, superscript, keyboard keys, underline and highlights:
H<sub>2</sub>Oneeds HTML. With Keep HTML on (the default) the tag is kept, and GitHub, GitLab, Hugo and Obsidian all render it. With it off you getH2O. - Merged cells and complex tables: kept as an HTML table, or flattened into a pipe table with empty cells when Keep HTML is off.
- Collapsible sections:
<details>and<summary>are kept as HTML with the body converted to Markdown between them, which is the pattern GitHub documents. - Links or emphasis inside inline code: a code span holds text only, so
<code><a href="…">fn</a></code>becomes`fn`. - Embeds and interactive elements: iframes, video, form controls and SVG are skipped.
javascript:links keep their text and lose the link.
CommonMark vs GitHub Flavored Markdown
CommonMark is the strict, fully specified core of Markdown. GFM adds pipe tables, ~~strikethrough~~, task lists (- [x]) and bare-URL autolinking. The output uses GFM syntax only for those extensions, so everything except tables, strikethrough and task lists also renders in a plain CommonMark parser. Hugo (goldmark), GitHub, GitLab, Obsidian and Docusaurus all support the GFM extensions.
Common Conversion Problems
- Text appears as a list or heading after conversion. The converter that produced it didn’t escape line starts. Text like
2024. Resultsneeds to be2024\. Results. - Words run together around bold or links. The spaces were inside the HTML tag and got trimmed. Convert again with this tool, which keeps them.
- Literal
**in the rendered output. That’s a flanking-rule failure (see above). Look for bold text that touches punctuation on the inside and a letter on the outside. - A table turned into one long line. A cell contained a line break or a list. Pipe tables need one line per row.
- Two lists became one, or a numbered list restarted at 1. That comes from a missing separator or an ignored
startattribute. Both are handled here. - Code block ends early. The code contained
```. Use a longer fence, which this tool does automatically.
Common Use Cases
- Migrating a blog to a static site generator. Paste each WordPress or Ghost post and drop the result into Hugo, Jekyll, Astro or Eleventy content folders.
- Moving documentation to GitHub. Turn Confluence or legacy HTML docs into README and wiki pages. Tables and code blocks keep their structure.
- Cleaning up editor output. WYSIWYG HTML full of
<span style>noise comes out as portable Markdown. - Notes and knowledge bases. Obsidian, Logseq, Notion imports and most headless CMSs store Markdown.
- LLM prompts. Markdown is far shorter than HTML for the same content, so converting a page before pasting it into a chat model saves tokens.
This Tool vs Turndown vs Pandoc
Turndown is the JavaScript library behind many browser extensions. It’s a good choice when you need conversion inside your own code. Its default escaping covers Markdown punctuation but not < or &, and it doesn’t check the flanking rules for emphasis. Pandoc is the command-line tool for bulk and multi-format work: pandoc -f html -t gfm page.html -o page.md converts a page, a shell loop handles whole folders, and it can write raw HTML for anything GFM can’t hold. Use this page when you have one snippet or one page to convert and want to check the result on the spot without installing anything.
Tips for Better Results
- Paste the article, not the whole page. Navigation built from plain
<div>s and<ul>s converts like any other content. - Prefer semantic HTML.
<strong>converts to bold, but<span style="font-weight:bold">is just text. - Check the preview. Paste the output into the Markdown to HTML converter to see it rendered, or tidy the source HTML first with the HTML beautifier.