Markdown is everywhere — GitHub READMEs, documentation, blog posts, Discord, Reddit, Notion, and more. Yet many developers only know the basics. This complete cheat sheet covers everything from headings to advanced features like footnotes, task lists, and diagrams.
Bookmark this for reference — you'll use it every day. 📌
What is Markdown?
Markdown is a lightweight markup language created by John Gruber in 2004. The philosophy: raw text should be readable as-is, with formatting syntax serving as natural visual cues rather than distracting code.
Where it's used:
- GitHub / GitLab (READMEs, Issues, PRs, Wikis)
- Stack Overflow, Reddit, Discord
- Notion, Obsidian, Typora
- Blog platforms (Dev.to, Hashnode, Ghost)
- API documentation (Swagger, Docusaurus)
- Jupyter notebooks
File extensions: .md or .markdown
Headings
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
Rule: Always put a space after the #. Use headings to create structure — don't skip levels (e.g., don't jump from H2 to H4).
Text Formatting
**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
`inline code`
Renders as:
- bold text
- italic text
- bold and italic
strikethroughinline code
Pro tip: Use **asterisks** for bold, not __underscores__. Asterisks work consistently everywhere — underscores can break mid-word in some parsers.
Links
[Inline link](https://example.com)
[Link with title](https://example.com "Hover text")
[Reference link][1]
[1]: https://example.com "Reference definition"
Auto-linking: On GitHub and Dev.to, bare URLs like https://example.com become clickable automatically.
Images
Note: Markdown doesn't support image sizing natively. For custom dimensions, use HTML:
<img src="image.png" alt="description" width="400" />
Lists
Unordered
- Item one
- Item two
- Nested item
- Another nested
- Item three
Ordered
1. First item
2. Second item
3. Third item
Fun fact: The actual numbers don't matter. You can write all 1. and the renderer will still number them correctly. This makes it easy to insert items without renumbering.
Task Lists (GitHub Flavored)
- [x] Completed task
- [ ] Incomplete task
- [ ] Another task
Renders as interactive checkboxes on GitHub! ✅
Code
Inline Code
Use `console.log()` to debug.
Fenced Code Block (with syntax highlighting)
```
javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
```
`
**Supported languages:** `javascript`, `python`, `typescript`, `html`, `css`, `json`, `bash`, `sql`, `go`, `rust`, `java`, `ruby`, `php`, `c`, `cpp`, `swift`, `kotlin`, and many more.
**Always specify the language** — syntax highlighting makes code dramatically easier to read.
---
## Blockquotes
```markdown
> This is a blockquote.
> It can span multiple lines.
> You can also
>> nest blockquotes
>>> multiple levels deep
```
### GitHub Alert Callouts
```markdown
> [!NOTE]
> This is a note callout.
> [!TIP]
> Helpful advice for the reader.
> [!WARNING]
> Something to be careful about.
> [!CAUTION]
> Potential danger or critical issue.
```
These render with colored icons on GitHub — incredibly useful for documentation! 🎨
---
## Tables
```markdown
| Feature | JSON | XML |
|---------|------|-----|
| Syntax | Clean | Verbose |
| Speed | Fast | Slower |
| Types | Yes | No |
```
### Column Alignment
```markdown
| Left | Center | Right |
|:-----|:------:|------:|
| L | C | R |
```
- `:---` = left align
- `:---:` = center align
- `---:` = right align
---
## Horizontal Rules
```markdown
---
***
___
```
All three produce the same horizontal line. Use `---` (most common convention).
---
## Escaping Special Characters
```markdown
\* Not italic \*
\# Not a heading
\[Not a link\]
\`Not code\`
```
Prefix any Markdown special character with `\` to render it literally.
---
## Advanced Features
### Footnotes
```markdown
Here's a statement with a footnote.[^1]
[^1]: This is the footnote content.
```
Supported on Dev.to, GitHub (in some contexts), and many static site generators.
### Definition Lists
```markdown
Term
: Definition of the term
Another Term
: Another definition
```
### Math (LaTeX)
```markdown
Inline: $E = mc^2$
Block:
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + ... + x_n
$$
```
Supported on GitHub, Jupyter, and platforms using MathJax/KaTeX.
### Mermaid Diagrams (GitHub)
`
```markdown
```
mermaid
graph LR
A[Start] --> B{Decision}
B -->|Yes| C[Do this]
B -->|No| D[Do that]
```
```
`
GitHub renders these as interactive diagrams directly in your Markdown! Perfect for flowcharts, sequence diagrams, and architecture docs.
---
## Quick Reference Table
| Element | Syntax |
|---------|--------|
| Heading | `# H1` `## H2` `### H3` |
| Bold | `**text**` |
| Italic | `*text*` |
| Strikethrough | `~~text~~` |
| Link | `[text](url)` |
| Image | `` |
| Inline code | `` `code` `` |
| Code block | `
``` ```
lang
```
` |
| Blockquote | `> text` |
| Unordered list | `- item` |
| Ordered list | `1. item` |
| Task list | `- [x] done` |
| Table | `\| col \| col \|` |
| Horizontal rule | `---` |
| Footnote | `[^1]` |
---
## Try It Yourself 🚀
I built a free **Markdown Preview** tool with a live editor, formatting toolbar, and instant HTML rendering — no signup needed:
👉 [StringToolsApp Markdown Preview](https://stringtoolsapp.com/markdown-preview)
Write Markdown on the left, see the rendered output on the right. Copy the HTML with one click. 100% client-side — nothing leaves your browser.
---
## Conclusion
Markdown is one of those skills that takes 10 minutes to learn but saves you thousands of hours over your career. Bookmark this cheat sheet and refer to it whenever you forget a syntax.
**What's your favorite Markdown feature?** Are you team `**asterisks**` or `__underscores__` for bold? Drop a comment! 💬
Top comments (0)