Markdown to HTML

How to Use This Tool

1. Paste the MarkdownA README, release notes, a documentation page — anything written in Markdown.
2. Decide about raw HTMLLeave escaping on for anything you did not write. Turn it off only for your own trusted source that deliberately contains tags.
3. Copy the HTML or check the previewSwitch to the preview to see the rendering, then copy the HTML source when it looks right.

How It Works

Conversion runs in two passes. The block pass walks the source line by line and recognizes structure: fenced code blocks first so nothing inside them is interpreted, then rules, headings, blockquotes, tables, lists, and finally paragraphs, with lists recursing so a nested list becomes a nested element. The inline pass then runs over each block’s text, extracting code spans before anything else so their contents are never treated as markup, then images, links, autolinks, and finally the emphasis and strikethrough markers. HTML escaping happens before the inline pass, which is why a script tag in the source is already inert by the time any pattern sees it.

Worked Examples

Why Raw HTML Is Escaped by Default

Markdown was designed to allow raw HTML. That is a deliberate feature of the original specification and it is genuinely useful when you are writing your own document and need a construct Markdown lacks. It is also the reason a Markdown converter is a security boundary rather than a formatting utility.

The moment a document you did not write is converted with raw HTML passed through, its author chooses what ends up in your page. A script tag is the obvious case; the subtler ones are an image with an onerror handler, an iframe, a form posting somewhere else, or a style block repositioning an element over a real button. All of them are legal HTML and all of them survive a converter that does not escape.

So escaping is on by default, and turning it off is a deliberate act. When it is off, tags pass through untouched — which is exactly right for your own README containing a deliberate detail element, and exactly wrong for a comment body, a user-submitted description, or anything arriving from an API. Independently of that switch, link and image URLs are always filtered against a scheme allowlist, so a javascript: href never survives the conversion in either mode.

The Preview Runs in a Sandbox

A rendered preview is the obvious feature for a Markdown tool and the obvious way to undo all of the care above. Injecting converted HTML into the page would give the source document a foothold in this page’s origin — the definition of a self-inflicted cross-site scripting bug, and a particularly awkward one on a site whose promise is that your input never goes anywhere.

The preview here is an iframe carrying a sandbox attribute with no allow-scripts token. That combination disables scripting, form submission, plugins, popups and same-origin access inside the frame. The converted markup renders and cannot execute, so the preview is honest about the layout without inheriting any of the risk.

It is a good illustration of a general point about this kind of tool: the safe design is not to sanitize harder, it is to render in a context where the dangerous thing cannot happen. Escaping handles the output you copy; the sandbox handles the output you look at.

Which Markdown, Exactly

There is no single Markdown. The 2004 original was defined by its implementation, CommonMark later specified the ambiguous parts, and GitHub Flavored Markdown added tables, task lists, strikethrough and autolinks on top. Different tools implement different overlapping portions, which is why a document that renders correctly in one editor can look wrong in another.

This converter covers the CommonMark core — headings, paragraphs, emphasis, code spans and fences, lists including nesting, blockquotes, rules, links and images — plus the four GitHub extensions above. Not implemented: reference-style links, footnotes, definition lists, and setext headings underlined with equals signs. A document using one of those renders its source text rather than dropping it, so the gap is visible on screen instead of appearing as missing content later.

Two behaviors are worth knowing because they differ between tools. A single newline inside a paragraph is a space, not a line break, unless you end the line with two spaces — the optional switch here makes every newline a break, matching what chat applications do. And underscores inside a word do not create emphasis, so a snake_case_identifier survives intact, which the original implementation got wrong often enough to be a running joke.

Where the HTML Goes Next

One caution before publishing. Documentation examples are a notorious place for a real API key to sit in a code fence, because the person writing the example pasted a working one. Converting the document does nothing about that — if a live credential is in there, treat it as public and generate a replacement rather than editing the example and hoping.

Most conversions here end in one of three places: an email template, a CMS field that accepts HTML but not Markdown, or a static page. All three want the HTML source rather than the preview, which is why the copy button always copies the source regardless of which view is showing.

If the HTML is going into a JSON payload — a request body, a fixture, a CMS API call — it has to survive being embedded in a string, and unescaped quotes and newlines are the usual thing that breaks it. Formatting and validating that JSON after pasting catches the problem in seconds rather than at request time. If the destination expects the markup wrapped for transport, Base64 encoding it sidesteps the quoting question entirely, though it is an encoding step and not a security one.

The conversion runs both ways, and the return trip is the one that matters during a migration: converting existing HTML pages to Markdown is how documentation gets out of an old CMS and into a repository. Round-tripping is stable for what Markdown can express and lossy for layout markup, so it is a migration aid rather than a channel.

Two smaller things save time on documents headed for publication. Headings written by several people drift between title case and sentence case, and normalizing them in one pass is quicker than editing each one. And a link whose URL contains a space, a bracket or a non-Latin character will not survive as written — percent-encoding it first avoids a link that looks right in the Markdown and breaks in the HTML.

For laying out a template before the real copy exists, generating placeholder paragraphs gives you body text with realistic density to convert and drop in. And when two versions of a document render differently and it is not obvious why, diffing the two HTML outputs localizes the change far faster than comparing the Markdown, because the structural difference is explicit in the tags.