Markdown: The Only Cheat Sheet You'll Actually Need
September 29, 2026 · 6 min read
I write almost everything in Markdown now — notes, docs, this blog. READMEs on GitHub, messages on Discord, cards in Notion: it's all Markdown underneath. If you've ever typed **bold** in a chat app and watched it turn bold, you already know Markdown. What follows isn't the complete spec (nobody needs the complete spec). It's the 20% you'll use 80% of the time, plus the gotchas that trip everyone up.
The absolute basics
# Heading 1 ## Heading 2 ### Heading 3 **bold** and *italic* and ***both*** - bullet item - another item - nested item 1. numbered item 2. second item [link text](https://example.com) 
That's genuinely most of daily Markdown. Headers with #, emphasis with asterisks, lists with - or numbers, links with [text](url). Learn these and you can write 90% of documents.
Code: the reason developers love Markdown
Inline code with single backticks: `const x = 1`. Code blocks with triple backticks, optionally naming the language for highlighting:
```python
def greet(name):
return f"Hello, {name}"
```
One gotcha: inside a code block, nothing is interpreted — no bold, no links, no formatting. That's the point. The other gotcha: if your code itself contains triple backticks, use four backticks to fence the block. You'll hit this exactly once and never forget it.
Quotes, dividers, tables
> This is a quote. Great for > replying to specific points. --- | Name | Role | |------|--------| | Ada | Admin | | Bo | Viewer |
Blockquotes with >, horizontal rules with ---, tables with pipes. Tables are the ugliest part of Markdown to write — aligning those pipes by hand is nobody's idea of fun — but they render fine even if your pipes don't line up. Don't stress about alignment; the renderer doesn't care.
The gotchas everyone hits
- Line breaks. A single newline in your source is treated as a space, not a line break. Want a hard break? End the line with two spaces (invisible and annoying), or just use a blank line for a new paragraph like a normal person.
- Blank lines matter. Headers, lists, and code blocks usually need a blank line before them to be recognized. "Why isn't my list rendering?" is blank-line-related about 80% of the time.
- Numbered lists auto-number. You can write
1.for every item and the renderer numbers them correctly. Handy when reordering — you never have to renumber. - Special characters. Want a literal
*or#? Escape it:\*. This bites people writing about Markdown in Markdown (very meta, very annoying). - Flavors differ. GitHub, Discord, Notion, and Reddit all have slightly different Markdown. Tables work on GitHub but not in all chat apps;
~~strikethrough~~works in some places and not others. When something doesn't render, it's usually the flavor, not you.
Why Markdown won
Before Markdown, formatted text meant either WYSIWYG editors (fine until you need version control or plain-text email) or raw HTML (precise but verbose). Markdown hit the sweet spot: readable as plain text, convertible to HTML, diffable in git, writable in any editor. That's why it ate documentation. Your README, your wiki, your static site generator, your AI chat transcripts — all Markdown, because plain text with light conventions turned out to be the most durable format we have.
Learn by doing
Reading about Markdown is the slow way. The fast way: open a preview tool, type on the left, watch it render on the right. Try every example above. Break things. That's how the syntax sticks.