Convert Markdown to HTML

A fragment or a page, and which you want

There are two useful outputs and they are not interchangeable. A fragment is just the converted markup — headings, paragraphs, lists, links — with no document wrapper, which is what you want when the result is going into a template, a CMS field or another page. A complete page adds the doctype, a head, a character-set declaration and a stylesheet, so it opens on its own and looks like something. Pasting a complete page into a CMS gives you a document inside a document; pasting a fragment into a browser gives you unstyled text.

The conversion covers the widely-agreed extended Markdown set: headings, emphasis, lists, links, images, block quotes, tables, fenced code blocks with syntax highlighting, task lists, strikethrough and footnotes. Headings get identifiers derived from their text, so they can be linked to directly — the anchor links that make long documentation usable.

Raw HTML inside the Markdown is passed through, which is part of the specification and worth being deliberate about: it means a Markdown file from an untrusted source can contain a script tag, and converting it produces a page carrying that script. Never render Markdown from strangers without sanitising the HTML afterwards — the conversion is not a security boundary and was never meant to be one.

Two things are output as code blocks rather than rendered, deliberately. Math formulas in LaTeX notation need a typesetting library, and Mermaid diagrams need a diagram renderer — each is a substantial dependency, and a misrendered equation is worse than a visible one. A complete page uses ordinary system fonts rather than fetching any, so it works offline and looks slightly different across Windows, macOS and Linux.

When you want something else

Pandoc handles the parts left out here and a great deal more: pandoc in.md -o out.html --mathjax --standalone --toc renders math properly, generates a table of contents, and accepts a template so the output matches your own site. It also converts to and from around forty other formats, which is why it is worth installing once.

For a website rather than a file, use a generator rather than converting pages one at a time. Hugo, Eleventy, Jekyll and MkDocs turn a folder of Markdown into a site with navigation, search and consistent styling, and rebuild it whenever the source changes — which is the actual job whenever there is more than one document.