📄 Markdown to HTML Converter

Complete Guide: Markdown to HTML Converter

Converting Markdown to HTML sounds simple, but doing it correctly — safely, consistently, and with all the modern extensions — requires understanding both the specification landscape and the security implications of raw HTML passthrough.

CommonMark vs Original Markdown

John Gruber's original Markdown spec from 2004 was intentionally vague in many areas, leading to incompatible behavior across parsers. CommonMark, finalized in 2019, is a rigorous, unambiguous specification that resolves these inconsistencies. It defines exact rules for edge cases like nested emphasis, lazy continuation lines in block quotes, and how many spaces constitute a code block.

Key differences you'll encounter:

• CommonMark requires a blank line before a list in most contexts; original Markdown did not always.
• Heading ATX style (## Heading) is strictly defined — no trailing # required but allowed.
• Indented code blocks use exactly 4 spaces; CommonMark is precise about mixed tab/space handling.

Most modern converters (marked.js, markdown-it, Python-Markdown 3+, Pandoc) default to CommonMark or offer it as an option. Always verify which spec your converter targets.

Security: Sanitizing Output (XSS via Raw HTML)

Markdown allows raw HTML passthrough by default. This means a user can embed <script>alert(1)</script> in a Markdown document and it will appear verbatim in the output — a critical XSS vector if you render user-supplied Markdown in a browser.

Never render unsanitized Markdown output directly into a webpage. Your options:

1. Disable raw HTML — most parsers have a html: false option that strips or escapes all raw HTML tags in the source.
2. Sanitize the output HTML — use a dedicated HTML sanitizer like DOMPurify (browser) or html-sanitizer (Node.js) after conversion. This allows a whitelist of safe tags while stripping dangerous ones.
3. Content Security Policy — a CSP header adds a defense-in-depth layer but is not a substitute for sanitization.

See also our HTML Entity Encoder for encoding individual special characters safely.

Use in Static Site Generators

Static site generators convert entire directories of Markdown to HTML at build time:

• Hugo uses Goldmark (CommonMark compliant with extensions)
• Jekyll uses kramdown by default (its own dialect)
• Eleventy is agnostic — you can configure markdown-it or any other parser

These tools process Markdown at build time, so XSS is less of a concern for authored content. However, if your SSG supports user-contributed content, sanitization still applies.

Adding Syntax Highlighting Post-Conversion

Markdown converters turn fenced code blocks into <pre><code class="language-js">...</code></pre>. Syntax highlighting is a second step applied to these elements:

• highlight.js — auto-detects language or reads the class, runs client-side
• Prism.js — lightweight, tree-shakeable, reads language-* classes
• Shiki — uses VS Code grammar files server-side, produces static HTML with inline styles (no client JS needed)

// highlight.js initialization after Markdown conversion:
import hljs from 'highlight.js';
document.querySelectorAll('pre code').forEach(el => hljs.highlightElement(el));

GitHub Flavored Markdown (GFM) Extensions

GFM adds features not in CommonMark: tables, ~~strikethrough~~, task list checkboxes, and autolinks. Tables use pipe syntax:

| Column A | Column B |
|----------|----------|
| Value 1  | Value 2  |

This renders to a proper <table> element. Not all converters support GFM tables by default — check your parser's extension configuration.

SEO-Friendly Heading IDs

For documentation sites, headings should have id attributes so they can be linked directly. Most converters can auto-generate IDs from heading text: ## My Section becomes <h2 id="my-section">My Section</h2>. Ensure your converter slugifies the heading text consistently (lowercase, hyphens for spaces, strip special characters).

Email-Compatible HTML from Markdown

Email clients support a very limited HTML subset. If you're generating email HTML from Markdown, you must inline all CSS (no external stylesheets, no <style> blocks in most clients), avoid <div> for layout (use <table>), and convert any relative URLs to absolute. Tools like Juice (Node.js) can inline CSS into the Markdown-generated HTML as a post-processing step.

Explore related tools: Markdown Editor for live preview, and HTML Entity Encoder for escaping special characters in your output.