Markdown and HTML Conversion, Explained
After reading this you will know what Markdown actually promises, how a converter turns it into HTML and back, and why round-tripping some documents loses information while others survive intact.
What the two formats are
Markdown is a plain-text writing format. You mark structure with a few punctuation characters, so # Title becomes a heading and *word* becomes italic. John Gruber released the first version in 2004 with a stated goal: the source should be readable as-is, before any conversion.
HTML is the markup the browser renders. The same heading is <h1>Title</h1> and the italic word is <em>word</em>. HTML is more verbose and can express far more than Markdown can.
A converter maps between them. Going one way, Markdown to HTML, is a well-defined process: the CommonMark specification (2014 onward) fixes exactly what each character sequence means. Going the other way, HTML to Markdown, is a best-effort reduction, because HTML holds structures Markdown has no syntax for.
Here is the hook. The five-character Markdown string **hi** produces the seventeen-character HTML <strong>hi</strong>. Convert that HTML back and you get **hi** again. The trip is lossless. Now try a <table> with merged cells: it cannot survive, because Markdown tables have no way to span cells.
When to convert, and when not
Convert Markdown to HTML when you have written in Markdown (a README, a forum post, notes) and need HTML for a web page or an email template. Convert HTML to Markdown when you want to edit or store content in a simpler form, for example pulling an article body out of a page and into a documentation repository.
Do not convert when the source depends on features the target lacks. Markdown cannot represent a colspan, a form field, a video embed, or arbitrary CSS classes. If your HTML relies on those, converting to Markdown will drop them silently.
Page-builder HTML with deeply nested <div> wrappers has no Markdown equivalent. It comes out as plain text with the structure gone. Check the preview before you rely on the result.
How the conversion works, step by step
Markdown to HTML runs in two phases, which CommonMark calls block parsing and inline parsing.
First the parser splits the text into blocks by looking at line starts. A line beginning with # is a heading. A blank line ends a paragraph. A line starting with - or * followed by a space starts a list item. A line indented four spaces or fenced with ``` is a code block.
Then, inside each block that allows it, the parser scans for inline markers: * and _ for emphasis, backticks for code spans, [text](url) for links. Code blocks are exempt, which is why `*x*` shows a literal asterisk instead of italics.
The reverse direction walks the HTML tree. Each element maps to its Markdown equivalent when one exists. An <h2> becomes ## , an <a href> becomes [text](href), an <li> becomes a - line. An element with no equivalent, such as a <span class="highlight">, has its tags stripped and its text kept.
Measuring what round-tripping costs
A useful way to judge a conversion is round-trip fidelity: convert Markdown to HTML, convert that HTML back to Markdown, and compare the two Markdown strings. Define the fidelity as the fraction of the original that survives unchanged.
Here L_{\text{orig}} is the character length of the original Markdown, and L_{\text{match}} is the length of the longest common subsequence shared with the round-tripped version. F = 1 means a perfect round trip; F = 0.8 means one character in five changed or vanished.
Plain features round-trip near F = 1. Feature-rich HTML drags F down. The point is not the exact number but the direction: the more your document leans on HTML-only structure, the lower the fidelity.
A worked example you can reproduce
Load the tool with its default sample and you get a small Markdown document. Walk through what each line becomes.
Converting a heading, a link and a list
Take this Markdown source, 78 characters including the newlines:
# HelloA **bold** word and a [link](https://example.com).- item one- item two
# Hellostarts with#and one space, so it is a level-1 heading:<h1>Hello</h1>.- The next line is a paragraph. Inside it,
**bold**becomes<strong>bold</strong>and[link](https://example.com)becomes<a href="https://example.com">link</a>. The whole line is wrapped in<p>...</p>. - The two
-lines form one list:<ul><li>item one</li><li>item two</li></ul>.
The HTML output runs to about 150 characters, roughly twice the source. Convert that HTML back and you recover the original Markdown almost exactly. The only likely change is spacing around the list, which does not affect the rendered result, so F \approx 1.00 here.
Reading the preview
The live preview renders the HTML so you see the finished result, not the tags. Use it as a check, not as the output. Two documents can render identically while their HTML differs. For instance *x* and _x_ both render as italic x, but they produce the same <em>x</em>, and a round trip back to Markdown will pick one spelling, usually *x*.
If a line renders as literal text when you expected formatting, the usual cause is a missing space. Markdown requires the space in # Heading and - item. Without it, #Heading is just a paragraph starting with a hash.
Common mistakes
Four errors account for most surprises.
- Missing blank lines around blocks
- A list or code block that touches the paragraph above it may merge into that paragraph. Put a blank line before and after block elements.
- Unescaped special characters
- To show a literal asterisk or underscore, escape it with a backslash:
\*renders as*, not as the start of emphasis. - Expecting raw HTML to always pass through
- CommonMark allows inline HTML, but a converter may strip or sanitise tags it does not recognise. Do not assume a
<script>or a custom attribute survives. - Losing structure on the way back
- Tables with merged cells, definition lists, and nested wrappers have no Markdown form. Converting such HTML to Markdown flattens them.
When a round trip matters, convert once, convert back, and compare the two Markdown strings directly. If they match, the document is safe to store as Markdown.
Related tools
If your source is forum markup rather than Markdown, the BBCode Converter turns BBCode into HTML, Markdown or plain text. Its trade-offs mirror the ones here: simple tags convert cleanly, and anything without a target equivalent falls back to plain text.
Frequently asked questions
Is the conversion lossless?
Markdown to HTML is faithful for every supported feature. HTML to Markdown is lossless only when the HTML uses structures Markdown can express. Headings, emphasis, links, images, lists, blockquotes and simple tables survive. Merged table cells, nested wrapper divs and custom attributes do not.
Which flavour of Markdown does this use?
The tool converts with a CommonMark-compliant library. CommonMark is the standardised specification, so *x*, backtick code spans and fenced code blocks behave as the spec defines rather than in a vendor-specific way.
Why did my HTML come out as plain text?
The HTML relied on structure with no Markdown equivalent, most often deeply nested <div> layers from a page builder. The converter keeps the text and drops the wrappers.
Does anything I paste get uploaded?
No. The conversion runs entirely in your browser, and the Markdown library is fetched once from a CDN. Nothing you paste leaves your device.
Can I write raw HTML inside my Markdown?
Yes, CommonMark permits inline HTML, and recognised tags pass through. Do not rely on unusual or unsafe tags surviving, since a converter may sanitise them.
Related tools
BBCode Converter
BBCode to HTML or Markdown, and plain text.
Case Converter
camelCase, snake_case, Title Case, UPPER, lower and more.
Fancy Text Generator
𝓗𝓪𝓷𝓭𝔀𝓻𝓲𝓽𝓲𝓷𝓰, sᴍᴀʟʟ ᴄᴀᴘs, zalgo and other Unicode styles.
Keyboard Layout Analyzer
Paste your text and see QWERTY, Dvorak and Colemak fight it out — finger heatmaps, travel and effort.
Line Tools: Dedupe, Sort & Shuffle
Remove duplicate lines, sort, reverse, shuffle, number.
Lorem Ipsum Generator
Placeholder text: classic lorem, Cicero, tech and corporate.