A complete reference for Markdown syntax — headings, lists, code blocks, tables, links, and GitHub-Flavored Markdown extensions used in READMEs and documentation.
Markdown is a lightweight markup language that converts plain text to formatted HTML. Created by John Gruber in 2004, it's now the standard for READMEs, documentation, blog posts, and developer notes across GitHub, GitLab, Notion, Obsidian, and most developer tools.
The philosophy: the source should be readable as-is, even without rendering.
# H1 — Page Title
## H2 — Section
### H3 — Subsection
#### H4 — Sub-subsection
Use one H1 per page (the document title). H2 for major sections, H3 for subsections.
**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
`inline code`
Renders as: bold, italic, bold and italic, strikethrough, inline code
Unordered:
- First item
- Second item
- Nested item (2 spaces indent)
- Another nested item
- Third item
Ordered:
1. First step
2. Second step
3. Third step
The actual numbers don't matter — Markdown auto-numbers them. Writing 1. 1. 1. still renders as 1, 2, 3.
Task lists (GitHub-Flavored Markdown):
- [x] Set up project structure
- [x] Write tests
- [ ] Add CI/CD
- [ ] Write documentation
Inline code uses single backticks: const x = 1
Fenced code blocks use triple backticks with an optional language specifier for syntax highlighting:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
Common language specifiers: `javascript`, `typescript`, `python`, `bash`, `sql`, `json`, `yaml`, `css`, `html`, `diff`
**Diff syntax** highlights additions and removals:
```diff
- const old = "remove this"
+ const new = "add this"
Links:
[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")
[Relative link](./docs/setup.md)
Reference-style:
[Google][google-ref]
[google-ref]: https://google.com
Images:
Add a link around an image to make it clickable:
[](https://example.com)
| Header 1 | Header 2 | Header 3 |
|-------------|-------------|-------------|
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |
Alignment:
| Left | Center | Right |
|:-------------|:-------------:|-------------:|
| Left-aligned | Centered | Right-aligned |
The colons in the separator row control alignment.
> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > Nested blockquote
Any of these create a horizontal divider:
---
***
___
GitHub's extended Markdown adds several useful features:
Mentions and references:
@username — links to a GitHub user
#123 — links to issue or PR #123
org/repo#123 — links to issue in another repo
Alerts (GitHub only, 2023+):
> [!NOTE]
> Highlights information users should notice.
> [!WARNING]
> Critical content demanding immediate attention.
> [!TIP]
> Helpful advice for better results.
Collapsible sections:
<details>
<summary>Click to expand</summary>
Hidden content here. Can contain any Markdown.
```bash
echo "Even code blocks"
A good README answers four questions immediately:
# Project Name
One-sentence description of what this does.
## Installation
```bash
npm install my-package
import { thing } from "my-package";
thing.doSomething();
| Method | Description |
|---|---|
thing.doSomething() |
Does the thing |
MIT
Add badges from shields.io for build status, npm version, and license:
```markdown
To display a literal character that Markdown would normally interpret, prefix with backslash:
*Not italic*
# Not a heading
[Not a link](not-a-url)
Markdown is one of those rare tools where five minutes of learning pays dividends for the rest of your career. It's used in GitHub READMEs, issue trackers, pull requests, wikis, documentation sites, blog platforms, and note-taking apps. Learn the core syntax well, and you'll write clearer documentation across every tool in your workflow.