Markdown to HTML

Markdown is quick to write and HTML is what the browser reads, so somewhere between the two there has to be a converter. This one parses your source properly — a full CommonMark implementation with GitHub's extensions on top — and then hands you the markup as source code you can read, adjust and paste.

Correct parsing is the part people notice only when it is missing. A list nested three deep keeps its structure. A table becomes a real table with a header row. A fenced code block keeps its line breaks and gains a language class, and any Markdown syntax inside it stays as literal text instead of being converted. Characters that mean something in HTML get escaped, so a paragraph about "5 < 6 && 7 > 6" produces valid markup rather than a broken tag. An underscore in the middle of "MAX_BUFFER_SIZE" stays where it is.

The second half of the job is the shape of what comes out, because generated markup has to fit somewhere. Pretty-printed with two spaces, four, or a tab; compact with one element per line; or minified to a single line — with code blocks left untouched in all three, since their whitespace is content. Void elements as "<br>" or "<br />". Single or double quotes. JSX attribute names if it is going into a React component.

And a set of decisions about what the markup should carry: GitHub-style ids on headings so anchors work, optional anchor links beside them, Bootstrap or Tailwind classes on the elements, a target attribute on links that leave the page, lazy loading on images, and either a bare fragment or a complete HTML document with a stylesheet. Raw HTML in the source is escaped by default, and the other two options are explicit about what they do.

Markdown permits raw HTML, which is convenient when it is your own document and a liability when it is not. Converting Markdown that came from a user and dropping the result into a page is one of the standard ways a cross-site scripting bug gets introduced — a script tag or an onclick attribute travels through the converter untouched and executes in your visitors' browsers.

So this converter asks rather than assumes. Escape, the default, turns any raw HTML into visible text: the safest option, and usually the right one for a content pipeline. Remove drops it entirely. Keep passes it through exactly as written, for source you control.

Keep does not claim to sanitise, and that is deliberate. A filter built from pattern matching can be worked around, and a converter that advertises safety it cannot deliver is more dangerous than one that is honest. Instead, Keep reports what it found — script tags, style blocks, iframes, inline event handlers, javascript: URLs — and says plainly that it left them alone. If you need untrusted HTML made safe, that is a job for a real sanitiser at the point of use.

The tempting way to build a Markdown converter is a list of find-and-replace rules: turn a line starting with a hash into a heading, turn double asterisks into strong, and so on. It works on a paragraph of prose and falls apart on everything else, because Markdown's meaning depends on context that a substitution cannot see.

The failures are specific and repeatable. A rule that converts headings has no idea it is inside a fenced code block, so a shell comment in your example turns into an h1. A rule that converts links runs before the rule that converts images, so an image becomes a link with a stray exclamation mark in front of it. A rule that turns underscores into emphasis cannot tell a word from a variable name, so a constant like MAX_BUFFER_SIZE comes out with italics in the middle. Nested lists need a parser that tracks indentation as state; there is no regular expression for it.

A parser builds a tree first and asks what each node is afterwards, so the context is never in doubt. This converter does that, which is why the cases above simply work — and why its output is a fair test of what a Markdown file will look like once it is published.

Correct HTML and usable HTML are not the same thing. Markup that is going into a React component needs className rather than class and every void element closed. Markup going into a file that uses tabs should not arrive indented with spaces. Markup that will be styled by a framework needs that framework's classes on its tables and blockquotes, and a build step that inlines a fragment does not want a doctype wrapped around it.

None of that changes the meaning of the document, which is exactly why it is worth making adjustable rather than picking one and hoping. Every option here is a property of the step that writes the tree out as text, so switching between them re-emits the same parsed document in a different shape.

One rule is fixed: the contents of a code block are never reformatted. Indentation inside a fenced block is content, not layout, so it survives pretty-printing, compacting and minifying alike. It is the single most common way an HTML formatter quietly corrupts a page.