Markdown to HTML

Every Markdown file is an HTML file waiting to be rendered, and the rendering is where it goes wrong: the README that looks fine on GitHub and falls apart in the CMS, the comment whose line breaks vanished, the table of contents whose links scroll nowhere. This page renders as you type, shows the HTML it made, lists the headings with their anchors, and points at the lines that will misbehave.

What comes out, and where it goes

The left pane is the editor. The right pane shows the same document three ways, one tab each. Preview is the rendered page, styled like an article rather than like a code box, so headings, tables and code blocks look the way they will in a real page. HTML is the generated source, indented by nesting so a <ul> inside a <li> reads as one. Outline is the heading tree with the anchor id each heading got, and a click on any entry scrolls the preview to it.

Three things leave the page. Copy HTML puts the source on the clipboard, download .html saves it under the title of the first heading, and copy as rich text puts the rendering on the clipboard as formatted text, so a paste into Gmail, Outlook, Word, Google Docs, Confluence or Notion arrives with its headings, lists, bold and links intact instead of as a wall of asterisks. That last one is the reason most people need a Markdown to HTML converter at all: the README is written, and someone wants it in an email.

The other reasons are quieter. Previewing a file before it lands in a commit, because the GitHub preview button only exists in the web editor. Getting HTML for a CMS, a newsletter tool or a wiki that has no Markdown field. Checking what a renderer does with a construct you are not sure about, with the HTML right there to read. Everything happens in this tab. The file is never uploaded, which matters for the internal runbook and the unreleased changelog.

Under the two panes sit the findings. They are the second half of the tool: a heading that jumps from h1 to h3, a second h1, an image with no alt text, a link with an empty target, a table row with the wrong number of cells (the usual state of a hand-edited table, a generated one from CSV to Markdown Table rarely has it), a code fence that never closes, a line that ends in two invisible spaces and will render a <br> nobody intended. Each row names the line, and a click puts the cursor there.

The five switches

--gfm

On by default, because GitHub is where most Markdown is read. It enables pipe tables, task lists (- [ ] and - [x]), strikethrough with ~~ and autolinks for bare URLs. Off means plain CommonMark: the table renders as a paragraph full of pipes, the checkbox stays as literal brackets, the URL stays text. The findings say so when a table or a bare URL is in the document and GFM is off.

--breaks

A single newline inside a paragraph becomes <br>, the way GitHub renders comments and issues and the way Slack and most chat tools read Markdown. Off is the CommonMark rule, and the rule GitHub applies to .md files: a newline is a space. marked only honours the switch in GFM mode, so with --gfm off it does nothing and the findings say so. The next section has the full story, because this switch is the most common reason two renderings of the same text differ.

--heading-ids

Gives every h1 to h6 an id computed the way GitHub computes its anchors, so a table of contents written for the README keeps working in the exported HTML. The outline tab shows the ids and copies the whole tree as a nested Markdown list.

--document

Wraps the fragment in a complete HTML5 page: doctype, <meta charset="utf-8"> (without it a browser opening the file from disk guesses the encoding and umlauts turn into mojibake), a viewport tag, the first h1 as <title> and a few lines of CSS so the file opens readably from disk. Off gives the bare fragment, which is what a CMS body field or a template slot wants.

--sanitize

Runs the HTML output through DOMPurify 3. Script tags, javascript: URLs, on* handlers and unknown elements disappear, and the findings count what was removed. Off passes raw HTML through untouched, with a note under the output. The preview is sanitized in both cases, for the obvious reason that it is rendered inside this page.

CommonMark vs GFM vs Markdown.pl

"Markdown" names three things that disagree. The original is Markdown.pl, John Gruber's Perl script from 2004, whose documentation is a prose description with a lot of unstated edge cases. CommonMark is the 2014 effort to write those edge cases down as a specification with a test suite of more than 600 examples, and it is what almost every modern renderer implements. GFM, GitHub Flavored Markdown, is CommonMark plus a fixed list of extensions, published by GitHub as its own spec in 2017.

The practical consequence is that a document written for GitHub carries tables, checkboxes and bare links that a strict CommonMark renderer turns back into text. Python-Markdown is the notable holdout on the other side, it still follows the Markdown.pl lineage and needs its tables and fenced_code extensions switched on before a GitHub README renders the way it does on GitHub. The --gfm switch above is the same difference, in one click, with the findings naming the constructs that would be lost.

Why GitHub READMEs and GitHub comments break lines differently

Same site, two rules. In a .md file GitHub follows CommonMark. A newline inside a paragraph is a soft break and renders as a space, so a paragraph wrapped at 80 columns in the editor flows as one paragraph. In issues, pull request descriptions and comments, GitHub switches to hard breaks: every newline is a <br>, because people writing comments expect Enter to mean a new line, the way it does in chat. Slack, Discord, Mattermost and most commenting systems use the second rule. Docs generators, static site builders and wikis use the first.

Both rules are a one-line option in every renderer: breaks: true in marked and markdown-it, the nl2br extension in Python-Markdown, +hard_line_breaks in pandoc. When a text renders with its line breaks in one place and without them in another, that option is the answer nine times out of ten. The tenth time, the source has two trailing spaces somewhere, which is a hard break in every dialect and invisible in every editor. The findings list those lines.

Heading anchors, the GitHub way

A table of contents in a README is a list of links to heading ids, and the ids are not in the file. GitHub generates them from the heading text when it renders, with a rule that is simple to state and easy to get wrong by hand, a URL slug without the transliteration: lowercase everything, keep letters, digits, spaces, hyphens and underscores, drop every other character, then turn spaces into hyphens. Duplicate headings get -1, -2 and so on in document order. Emoji and punctuation vanish entirely, which is how ## Set-up & Install turns into #set-up--install with two hyphens in a row, one from the original hyphen and one from the space that stood next to the ampersand.

## Set-up & Install

- [Install](#Set-up-&-Install)

→ scrolls nowhere: no uppercase, no & in the id

## Set-up & Install

- [Install](#set-up--install)

→ lowercase, & dropped, the space became a second hyphen

Two details bite in practice. Inline code in a heading keeps its text but loses the backticks, so ## The `--breaks` flag becomes #the---breaks-flag, three hyphens. And GitHub prefixes the real DOM id with user-content- and resolves the bare fragment with a script, so a TOC copied from a GitHub page into another site works only if that site generates the same ids. Exporting the HTML with --heading-ids on keeps the links working outside GitHub, and the outline tab's copy as Markdown TOC writes the list with the computed anchors so there is nothing to guess.

HTML inside Markdown, and why the preview sanitizes

Raw HTML is part of the syntax. CommonMark passes inline tags and HTML blocks through unchanged, which is what makes <details>, <kbd>, <img width="300"> and <p align="center"> possible in a README. It is also what makes every Markdown renderer an HTML injection vector the moment it renders text written by someone else. The payloads are not exotic:

• <script>alert(1)</script> as an HTML block, passed through verbatim.
• <img src=x onerror="alert(1)">, an event handler on a broken image.
• [click](javascript:alert(1)), pure Markdown syntax, no angle bracket anywhere. marked turns it into <a href="javascript:alert(1)"> without complaint.

Renderers handle this differently, and the difference is worth knowing before picking one. marked documents that it does not sanitize and tells you to run the output through DOMPurify. markdown-it escapes raw HTML unless html: true is set and refuses javascript:, vbscript: and data: links out of the box. GitHub passes HTML through and then filters it server-side, the GFM spec's tagfilter removes <script>, <style>, <iframe>, <textarea> and a handful more, and GitHub's own filter goes further and strips every on* attribute and every style.

The preview on this page is sanitized with DOMPurify whether or not --sanitize is on, because it is injected into this page's DOM and an unsanitized preview would execute whatever was pasted. The switch only decides whether the HTML you copy out is cleaned too. Leave it on unless the output goes into a system that sanitizes on its own or the Markdown is entirely yours.

Converting in code

The converter above runs marked 18 in the browser. The same call works in Node, and the output shows the GFM extensions at work: the task list becomes a disabled checkbox, the tildes become <del>, the bare URL becomes a link.

$ node -e "const {marked}=require('marked');process.stdout.write(marked.parse('- [x] tables\n\nSee ~~v1~~ https://example.com'))"
<ul>
<li><input checked="" disabled="" type="checkbox"> tables</li>
</ul>
<p>See <del>v1</del> <a href="https://example.com">https://example.com</a></p>

The other renderers, with the one line that matters for each:

One habit that has paid for itself is to render the same README with the renderer the deployment target uses, not the one the editor uses. VS Code previews with markdown-it, GitHub renders with its own build of the GFM parser, the docs site might run remark. They agree on ninety-five percent of a document and disagree on the footnote, the alert box and the raw HTML tag that one of them filters, which a diff of the two HTML outputs shows in seconds. The cost of the habit is a second tool in the loop, which is why this page exists.

The way back

HTML to Markdown is lossy and still useful, for pulling a page into a wiki or turning an email into an issue. Turndown is the JavaScript library for it, pandoc -f html -t gfm the command line. Tables, nested lists and anything styled with CSS are where both need a second look.

Which renderer, where

marked when the job is "Markdown in, HTML out" and speed or bundle size matters, with DOMPurify behind it whenever the text is not your own. markdown-it when you need plugins: footnotes, custom containers, heading anchors, emoji, all exist and compose. remark when you need the syntax tree, because you are transforming the document (linting it, extracting headings, embedding components) rather than just printing it. pandoc when the output is a document in the human sense, a docx for the client or a PDF for the release, and when the input is not Markdown at all.

That advice is wrong in one case, when the output has to match GitHub exactly. A README preview inside a tool, a bot that renders issue bodies, a docs site that promises "renders like GitHub". Every JavaScript renderer deviates from GitHub in corners. marked passes a <script> block through where the tagfilter escapes it, and both marked and markdown-it turn a footnote [^1] into a plain link whose href is the footnote text, and leave a > [!NOTE] alert as a blockquote with brackets in it. For that job use the GFM reference parser cmark-gfm through its bindings, or GitHub's Markdown API, and accept the network call.

The tool above uses marked, for the same reason the first line of the verdict does.

Markdown rendering questions