Markdown to HTML
Summary
Definition: Markdown to HTML conversion renders Markdown syntax into equivalent HTML elements.
Why it matters: HTML is the universal format for publishing and styling content on the web.
Pitfall: Markdown permits raw HTML, which can be unsafe without sanitization.
Key terms
- Markdown
- Lightweight text format designed for HTML conversion.
- HTML
- Standard markup language for web pages.
- CommonMark
- Formal, unambiguous Markdown specification.
- GFM
- CommonMark-based Markdown with extensions.
- Sanitization
- Removing unsafe HTML before publishing.
Standards and flavors
Markdown is not a single standard. Behavior depends on the specification and renderer.
Specs
Original
Informal spec by John Gruber.
CommonMark
Precise, testable core spec.
GFM
CommonMark plus tables and task lists.
How Markdown maps to HTML
Block elements map directly to HTML tags.
- Headings map to h1–h6 elements.
- Lists map to ul or ol elements.
- Code fences map to pre and code elements.
- Blockquotes map to blockquote elements.
Inline syntax also maps predictably.
- Emphasis maps to em and strong.
- Links map to a elements.
- Images map to img elements.
Common mix-up: Markdown replaces HTML. It simplifies authoring but does not cover all layout needs.
Quick example
Example
Simple Markdown headings and lists.
Markdown input
# Title
- Item one
- Item twoExample
Equivalent HTML produced by a CommonMark parser.
HTML output
<h1>Title</h1>
<ul>
<li>Item one</li>
<li>Item two</li>
</ul>Safety and correctness
Raw HTML in Markdown can introduce XSS risks if input is untrusted.
- Use a CommonMark-compliant parser.
- Sanitize HTML output before publishing.
- Test output against real content.
Practical check
Before publishing
- Convert Markdown using a known spec.
- Verify headings, links, and lists.
- Confirm code blocks render correctly.
- Sanitize output if input is untrusted.