Developer Tools·4 min read

How Markdown Converts to HTML: Tags, Lists, and Code

Markdown is a set of shorthand rules, and HTML is what those rules compile to. Understanding how markdown converts to html saves you from mystery formatting bugs: the missing blank line that glues a list to a paragraph, the heading that renders as plain text, the code block that swallowed half the document. This guide maps the common Markdown constructs to their HTML output, works through a real snippet in the Markdown to HTML tool, and covers the GitHub flavored extras that most sites now expect.

Open the tool All insights

From README to web page

The scenario.

Markdown wins wherever developers write: READMEs, changelogs, wikis, docs folders. Sooner or later that content needs to appear on an actual site, a help center article, a release notes page, a blog post in a CMS, and the site wants markup, not hash marks and asterisks.

Rewriting by hand invites errors and takes an hour you don't have. Conversion is mechanical, which is exactly why a tool should do it: the rules are fixed, and marked.js applies them the same way every time. The catch is that Markdown's rules are stricter than they look, and small slips in the source produce markup you didn't intend, which is why knowing the mapping matters.

How markdown converts to HTML, element by element

The mapping is small enough to keep in your head. A line starting with one hash becomes an h1, two hashes an h2, down through h6. Text wrapped in double asterisks becomes a strong element, single asterisks become em. A [label](url) pair turns into an anchor tag, and paragraphs separated by blank lines become p elements.

Lists follow the same logic: lines starting with hyphens produce a ul with an li per item, numbered lines produce an ol. A line opening with a greater-than sign becomes a blockquote. That blank-line rule does more work than people expect, and most conversion surprises trace back to it.

A three-line markdown example, converted

Take a three-line snippet. Input: ## Release notes, followed by a list with two items, - Fixed **login** bug and - Added [docs](https://example.com).

The HTML tab shows the output: <h2>Release notes</h2> followed by <ul><li>Fixed <strong>login</strong> bug</li><li>Added <a href="https://example.com">docs</a></li></ul>. Paste those lines into the Markdown to HTML tool and the Preview tab renders the result while the HTML tab shows these exact tags, updating live as you type. Copy HTML grabs the whole output once it looks right.

Inline code follows the same pattern: single backticks around a word produce a code element, so a command like npm install stays monospace inside the sentence. Emphasis nests too, meaning bold text with italics inside compiles to a strong element wrapping an em, exactly as you'd write the tags by hand.

GitHub flavored markdown extras

Plain Markdown covers the basics; the github flavored markdown extras cover what technical writing actually needs. Fenced code blocks, three backticks with an optional language hint, become pre and code elements carrying a language class your syntax highlighter can use. That class matters more than it looks: highlighters like Prism and Shiki key off language-js or language-python to choose a grammar. Pipe-separated rows become real table elements. Double tildes produce strikethrough, and bare URLs turn into links on their own.

The converter enables these by default because most content written today assumes them. If your snippet renders correctly on GitHub, the output here will match what you expect.

Mistakes that garble the converted output

Nearly every 'the converter is broken' report turns out to be one of these five.

No blank line before a list or heading. The parser glues it to the previous paragraph and your list renders as one line of hyphens.
An unclosed code fence. Everything after the orphan backticks becomes code, which is why half the document just turned monospace.
Accidental four-space indentation, which triggers an indented code block where you meant a paragraph.
Skipped heading levels, jumping from h1 to h4. Browsers render it fine, but the document outline and your SEO both suffer.
Curly quotes pasted from a word processor into code spans, which break the moment someone copies the snippet and runs it.

Markdown for cms content without the mess

Treat Markdown as the source of truth and commit it; generate the markup at publish time so edits stay diffable. When your CMS only offers an HTML body field, copy from the HTML tab, never from the rendered Preview, because a rendered copy drags styled spans along with it.

Using markdown for cms content that visitors submit? Convert it, then sanitize the result on the server, since raw HTML embedded in Markdown passes through the parser untouched.

When you need the opposite direction

This page has a mirror: HTML to Markdown takes existing markup back to portable text, which is the tool you want mid-migration. To inspect what the converter produced, paste the output into the HTML Beautifier and read it indented. And once the markup ships on a real page, the HTML Minifier strips the whitespace you no longer need. The three chain naturally during a publish: convert here, inspect there, compress last.