Markdown — Practical Cheatsheet
An example-driven guide to writing Markdown for READMEs, notes, and docs.
0) What is Markdown?
Plain text with simple syntax that renders as formatted content almost everywhere (GitHub, editors, note apps).
- Easy to write, easy to read as plain text
- Portable across tools
- Great for version control
1) Headings & Paragraphs
Example
# H1 Title
## H2 Section
### H3 Subsection
#### H4
##### H5
###### H6
This is a normal paragraph of text.
Another paragraph — leave a blank line between paragraphs.
Tip: Leave a blank line before and after headings and lists to avoid weird joins.
2) Emphasis, Inline Code, and Strikethrough
Example
*italic* or _italic_
**bold** or __bold__
***bold italic***
~~strikethrough~~
Inline code: `npm run start`
3) Blockquotes
Example
> This is a quote.
> It can span multiple lines.
>
> - You can include lists
> - inside quotes too.
4) Lists (Bulleted, Numbered, Nested) & Checklists
Example
- bullet item
- another item
- nested bullet
- another one
1. first
2. second
1. nested number
2. another
- [ ] to-do (unchecked)
- [x] to-do (done)
Tip: Indent nested items by two spaces (or a tab).
5) Links & Images
Example
[inline link](https://example.com)
[link with title](https://example.com "hover title")
Alt text matters for accessibility and when images fail to load.
6) Code Blocks (Fenced)
Use three backticks, and optionally a language for syntax highlighting.
Example
```bash
# install
npm i
# run
npm run start
type User = { id: string; name: string }
Common language tags: `bash`, `sh`, `json`, `js`, `ts`, `python`, `yaml`, `dockerfile`, `html`, `css`.
7) Tables (GitHub-Flavored Markdown)
Example
| Feature | Support | Notes |
|------------|---------|-----------------------|
| Tables | ✅ | GitHub & most viewers |
| Checklists | ✅ | `- [ ]` / `- [x]` |
| Footnotes | ✅ | See below |
Tip: The header separator line needs pipes and dashes, but spacing is flexible.
8) Footnotes (GitHub-Flavored Markdown)
Example
This sentence has a footnote.[^1]
[^1]: Here is the footnote content.
9) Horizontal Rules
Example
---
Three dashes (or *** / ___) on their own line.
10) Collapsible Sections (HTML details)
Works in many renderers (e.g., GitHub):
Example
<details>
<summary>Show more</summary>
Hidden content, notes, or screenshots can go here.
</details>
11) Line Breaks
- End a line with two spaces to force a line break
like this. - Or use
<br>.
Example
First line␠␠
Second line
Or use<br>HTML break.
12) Escaping Characters
Use backslash \ to escape special characters.
Example
\*this is not italic\*
Use a backtick in text: \`
13) Emojis & Symbols
Just type Unicode emojis (they render in most places):
✅ 🔐 🧠 ⚙️ 📘
14) Minimal README Template (Copy/Paste)
# Project Name
One-line description.
## 🚀 Quick Start
```bash
npm i
npm run start
📦 Features
- Item 1
- Item 2
- Item 3
🛠️ Scripts
npm run start– dev servernpm run build– production build
📁 Structure
.
├── src/
├── docs/
└── README.md
📄 License
MIT © Your Name
---
## 15) Common Pitfalls
- Forgetting blank lines around blocks (headings, lists, code)
- Mismatched code fences (opening ``` without a closing one)
- Missing alt text for images
- Indentation errors in nested lists
- Using tabs/spaces inconsistently (prefer two spaces)
---
## 16) Handy Editor Tips
- **Preview in VS Code:**
- Toggle preview: **Cmd+Shift+V** (Mac) / **Ctrl+Shift+V** (Win/Linux)
- Open preview to the side: **Cmd+K, V** / **Ctrl+K, V**
- **Useful extensions:**
- *Markdown All in One* (shortcuts, TOC)
- *Markdownlint* (style & consistency)
---
### You’re ready
Start simple: headings, paragraphs, lists, code blocks. Add tables, footnotes, and collapsible sections as needed. Markdown is meant to be quick and forgiving—write first, polish later.