What is Markdown? Syntax Guide with Examples
Markdown is a lightweight formatting language that converts plain text to HTML. Learn the Markdown syntax — headings, bold, lists, links, code blocks — and where Markdown is used today.
What Markdown is
Markdown is a plain-text formatting syntax created by John Gruber in 2004. You write normal text with a handful of punctuation symbols to indicate formatting — and a Markdown processor converts it to HTML.
The goal was to make formatted writing readable as-is. Unlike HTML, a Markdown document is still human-readable in its raw form — you can understand it without knowing the syntax.
# Hello World This is **bold** and this is *italic*. - Item one - Item two
Hello World
This is bold and this is italic.
- Item one
- Item two
Core Markdown syntax
| Markdown | Renders as |
|---|---|
| # Heading 1 | Large heading (H1) |
| ## Heading 2 | Subheading (H2) |
| **bold text** | Bold text |
| *italic text* | Italic text |
| ~~strikethrough~~ | Strikethrough text |
| [Link text](url) | Clickable hyperlink |
|  | Image |
| - Item | Unordered list item |
| 1. Item | Ordered list item |
| `inline code` | Inline code (monospace) |
| ```\ncode block\n``` | Fenced code block |
| > quoted text | Blockquote |
| --- | Horizontal rule |
| | Col | Col | | Table column separator |
Where Markdown is used
| Platform | Use |
|---|---|
| GitHub | README files, issues, pull request descriptions, wikis |
| Stack Overflow | Questions, answers, comments |
| Notion | Pages and documents |
| Slack / Teams | Message formatting (subset of Markdown) |
| Post and comment formatting | |
| Jekyll / Hugo | Static site generator content |
| Jupyter | Notebook cell documentation |
| Discord | Message formatting |
Markdown vs HTML — when to use each
Markdown is ideal for writing content — documentation, README files, blog posts, notes. It is faster to write and easier to read in source form.
HTML is better for precise layout control — custom styles, complex tables, specific attributes. Most Markdown processors also accept raw HTML inline, so you can mix both when needed.