Markdown to HTML

How to use Markdown to HTML

1. Paste your Markdown.
2. The HTML appears alongside it.
3. Copy it into your page or template, and add styling for the bare elements.
4. A single newline joins lines into a paragraph; use a blank line or two trailing spaces for a break.
5. Raw HTML in the Markdown passes through — sanitise anything user-supplied.
6. The output has no classes and no image dimensions; both usually need adding.

There is no single Markdown

John Gruber’s 1.0 description from 2004 left plenty ambiguous, and implementations diverged. CommonMark is the strict specification that settles those cases. GitHub Flavored Markdown adds tables, task lists, strikethrough and automatic linking on top of it, and is what most people mean when they say Markdown today. Notion, Obsidian, Discord and Slack each add or omit things. So Markdown that renders correctly in one place can render differently in another, particularly around nested lists and line breaks.

The line-break rule that surprises everyone

A single newline in Markdown does not produce a line break — consecutive lines are joined into one paragraph, which is deliberate, so that prose can be wrapped in a source file without affecting output. To force a break you need either two trailing spaces at the end of the line, which are invisible and get eaten by editors that trim whitespace, or a backslash, or a blank line to start a new paragraph. GitHub renders single newlines as breaks in comments and issues but not in files, which is why the same text behaves differently in two places on the same site.

Markdown allows raw HTML, and that matters for safety

You can drop HTML directly into Markdown, and most converters pass it straight through. That is convenient for a video embed or an attribute a converter cannot express — and it means Markdown from an untrusted source is exactly as dangerous as untrusted HTML. If you accept Markdown from users, sanitise the rendered output; do not assume the format is safe because it looks like plain text.

Where the output still needs work

Converted HTML carries no classes, so it inherits whatever your stylesheet says about bare h2, p and ul elements — which in a modern CSS reset is usually nothing. Either write styles for a wrapping class, or use a typography plugin. Images come through without width and height attributes, so add them to avoid layout shift. And code blocks come through as plain pre and code without syntax highlighting, which is a separate step.