Why Markdown Became the Universal Writing Standard
Created in 2004 by John Gruber and Aaron Swartz, Markdown was designed with a simple philosophy: formatted text should be completely legible and natural to read in its raw, unrendered plain-text form.
Writing documentation directly in raw HTML requires tedious typing of opening and closing tags (`<p>`, `<h1>`, `<em>`), breaking writing flow. Markdown allows writers and developers to format documentation using intuitive punctuation marks (like asterisks for emphasis and hashes for headings). Today, GitHub, Reddit, Notion, Discord, Stack Overflow, and modern static site generators (Next.js, Astro, Hugo) treat Markdown as their native publishing dialect.
Core CommonMark Syntax: Headings, Emphasis & Lists
CommonMark standardizes the core grammatical foundations across all platforms:
- Headings: Prefix text with 1 to 6 hash symbols (`# H1`, `## H2`, `### H3`). Always leave a space after the hashes.
- Emphasis: Wrap text in single asterisks `*italic*` or underscores `_italic_` for italics; use double asterisks `**bold**` for strong emphasis.
- Blockquotes: Prefix lines with the greater-than symbol (`> quoted text`). Supports nesting (`>> nested quote`).
- Hyperlinks: Wrap link anchor text in square brackets followed by the destination URL in parentheses (`[Tool Yaar](https://www.toolyaar.com)`).
- Images: Same syntax as links preceded by an exclamation mark (``).
GitHub Flavored Markdown (GFM): Tables, Tasks & Code
Standard CommonMark lacked tables, code highlighting, and checklist items. GitHub Flavored Markdown (GFM) introduced several essential extensions:
• Fenced Code Blocks: Wrap code in triple backticks with optional language identifiers for syntax highlighting (e.g., ```typescript ... ```).
• Interactive Task Lists: Unordered lists with `[ ]` for pending tasks and `[x]` for completed tasks.
• GFM Tables: Construct tabular data using vertical pipes (|) and hyphens (-), with colons (:) specifying text alignment (left, center, right).
• Strikethrough: Wrap text in double tildes (`~~deleted text~~`).
The Parsing Pipeline: AST Generation to HTML Output
Converting Markdown into production HTML involves a multi-stage compilation pipeline:
1. Tokenization: The lexer scans raw string text and breaks it into tokens (heading tokens, paragraph tokens, delimiter runs).
2. Abstract Syntax Tree (AST): Parsers like Remark or Unified construct a hierarchical tree of nodes representing document structure.
3. HTML Serialization: The AST is traversed to emit clean, semantically valid HTML tags (`<h1>`, `<pre><code>`, `<table>`).
Security: Sanitizing Raw HTML and Preventing XSS Attacks
Standard Markdown specifications explicitly permit embedding raw HTML tags inside Markdown documents. While convenient for advanced layouts, allowing arbitrary HTML creates dangerous Cross-Site Scripting (XSS) vulnerabilities if users can input `<script>` or `<img onerror=...>` vectors.
Whenever rendering user-supplied Markdown in a web application, always pipe the rendered HTML through a rigorous sanitization library (such as DOMPurify) before injecting it into the DOM with `dangerouslySetInnerHTML`.
Always Sanitize User Content
Never trust user-submitted Markdown without sanitization. An unsanitized Markdown previewer can easily execute malicious JavaScript in the victim’s browser.
Markdown to HTML Conversion Cheat Sheet
Direct mapping of Markdown syntax to emitted HTML tags:
| Markdown Syntax | Rendered HTML Output | Visual Representation |
|---|---|---|
| # Main Heading | <h1>Main Heading</h1> | Top-level page title |
| **Bold Text** | <strong>Bold Text</strong> | Heavily weighted bold lettering |
| *Italicized* | <em>Italicized</em> | Slanted emphasis text |
| `const x = 10;` | <code>const x = 10;</code> | Monospace inline code span |
| [Link](https://site.com) | <a href="https://site.com">Link</a> | Clickable hyperlink |
| > Important notice | <blockquote>Important notice</blockquote> | Indented callout block |
| - Item list | <ul><li>Item list</li></ul> | Bulleted list element |