Markdown syntax and the CommonMark specification
Markdown is a lightweight markup language created by John Gruber in 2004, designed to be readable as plain text while converting to clean HTML. A heading is a line starting with # signs; bold is **text**; a link is [label](url); a code block is indented 4 spaces or fenced with triple backticks. The original Markdown spec left many edge cases ambiguous, leading to inconsistent rendering across GitHub, GitLab, Slack, VS Code, Notion, and other tools. CommonMark (2014) formalised a unambiguous specification that is now the basis for GitHub Flavored Markdown (GFM), which adds tables, task lists, and fenced code blocks with syntax highlighting to the base spec.
| Syntax | Renders as |
|---|---|
# Heading 1 | H1 heading |
## Heading 2 | H2 heading |
**bold** or __bold__ | bold text |
*italic* or _italic_ | italic text |
[text](url) | Hyperlink |
 | Image |
- item or * item | Unordered list item |
1. item | Ordered list item |
`code` | Inline code |
| Triple backticks | Fenced code block (with optional language) |
> text | Blockquote |
--- | Horizontal rule |
Where Markdown is used and rendering differences
Markdown is ubiquitous in developer workflows: GitHub and GitLab README files, pull request descriptions, issue templates, wiki pages, documentation sites (Docusaurus, MkDocs, Jekyll), blog platforms (Ghost, Hugo, Gatsby), note-taking apps (Obsidian, Notion, Bear), and chat tools (Slack, Discord, each using a subset). Rendering differences between platforms are common: GitHub renders tables and task lists; older renderers may not. The preview here renders standard CommonMark, check the platform-specific documentation for extensions like ==highlight==, ~~strikethrough~~, and ^superscript^ which are not part of core CommonMark.
Related: HTML formatter (Markdown compiles to HTML), YAML formatter for front-matter in Markdown files, JSON formatter for API responses that contain Markdown strings.