Markdown has become the default writing format for technical documentation, READMEs, and content management systems. But to display in a browser, it needs to be converted to HTML. This guide explains how Markdown-to-HTML conversion works, the tools available, and the…
Markdown has become the default writing format for technical documentation, READMEs, and content management systems. But to display in a browser, it needs to be converted to HTML. This guide explains how Markdown-to-HTML conversion works, the tools available, and the gotchas to watch out for.
Why Markdown?
Markdown was created by John Gruber in 2004 as a way to write HTML using a natural, readable plain-text syntax. The goal was simple: Markdown source should be legible as-is, without looking like it’s been tagged up with HTML. A decade later, it’s the dominant format for developer documentation, GitHub READMEs, and countless note-taking tools.
The Core Markdown Syntax
- Headings:
# H1,## H2,### H3 - Bold/Italic:
**bold**,*italic*,***bold italic*** - Links:
[text](url) - Images:
 - Code: backtick for inline, triple backtick for code blocks
- Lists: – or * for unordered, 1. for ordered
- Blockquotes: > prefix
- Horizontal rules: — or ***
CommonMark: The Standardized Specification
One of Markdown’s historical problems was ambiguity — different parsers handled edge cases differently. CommonMark is a rigorous specification that defines exactly how Markdown should be parsed. GitHub Flavored Markdown (GFM) extends CommonMark with tables, task lists, and strikethrough. When choosing a Markdown parser, prefer one that implements CommonMark.
Security: Sanitizing Markdown-Generated HTML
Never render user-submitted Markdown directly as HTML without sanitization. Markdown allows raw HTML, which means a malicious user could inject <script> tags. Use a sanitization library (DOMPurify, Bleach, or your framework’s built-in escaping) after converting Markdown to HTML if the source is user-generated content.
Popular Markdown Parsers by Language
- JavaScript: marked, markdown-it, remark
- Python: python-markdown, mistune
- PHP: Parsedown, league/commonmark
- Ruby: kramdown, Redcarpet
- Go: goldmark, blackfriday
Conclusion
Markdown-to-HTML conversion is a fundamental operation in modern web development. Whether you’re building a documentation site, processing user input, or converting READMEs, understanding how the conversion works — and the security implications of rendering user-generated Markdown — will help you build better applications.