What Is Markdown? The Formatting Language You're Already Using

If you've used Claude, ChatGPT, Notion, Slack, Discord, or GitHub, you've seen Markdown, even if you didn't know its name. It's a way to add formatting to plain text using a few simple symbols. It takes ten minutes to learn, and you'll use it for the rest of your time building things.

The idea

Markdown lets you write formatting as you type, in a way that's still readable as plain text:

# Shopping list

- **Milk** (oat)
- Bread
- *Maybe* coffee

Displayed by a Markdown-aware tool, that becomes a heading, a bulleted list, bold, and italics. In a plain text editor, it's still perfectly readable.

Markdown files end in .md. README.md, CLAUDE.md, CHANGELOG.md, and most documentation are Markdown. (How to Write a README.)

The basics

Headings

# Heading 1
## Heading 2
### Heading 3

Use one # heading for the title, then ## for sections. A space after the # is required.

Emphasis

*italic* or _italic_
**bold**
~~strikethrough~~

Lists

- Bullet item
- Another item
  - Indented sub-item

1. First
2. Second
3. Third

Links and images

[Link text](https://example.com)
![Alt text describing the image](screenshot.png)

The image syntax is the link syntax with a ! in front.

Quotes

> This is a quoted paragraph.

Horizontal rule

---

Paragraphs and line breaks

Separate paragraphs with a blank line. A single line break usually does nothing — the lines join into one paragraph. This is the most common beginner surprise.

Code

For code within a sentence, use single backticks: `npm install` shows as npm install.

For blocks of code, use three backticks on their own lines, optionally followed by the language for syntax highlighting:

```bash
npm install
npm run dev
```

This is the single most useful Markdown feature for developers. When you paste an error message into a GitHub issue, a chat, or an AI tool, wrap it in a code block so its formatting survives.

Tables

| Plan    | Price | Databases |
| ------- | ----- | --------- |
| Starter | $20   | —         |
| Team    | $60   | Yes       |

The dashes separate the header row. Columns don't need to line up in the source; they're aligned when displayed.

Task lists

GitHub and many tools support checkboxes:

- [x] Set up database
- [ ] Add login
- [ ] Deploy

"Flavours" of Markdown

The original Markdown was small, and different tools added features. GitHub Flavored Markdown (GFM) — tables, task lists, strikethrough — is the de facto standard, and what most tools support. A few extras vary by tool:

Front matter — a block between --- lines at the top of a file, holding settings like a title and date. Blogs and documentation sites use it (this post has one).
Diagrams — GitHub renders mermaid code blocks as diagrams.
Callouts — GitHub supports > [!NOTE] and > [!WARNING] boxes.

Why AI tools love Markdown

AI models write Markdown naturally, which is why chat responses have headings, lists, and code blocks. It works the other way too: structuring your prompts in Markdown — headings for sections, lists for requirements, code blocks for errors — makes them clearer to the model. (How to Prompt AI Coding Tools.)

Instruction files like CLAUDE.md are Markdown for the same reason: readable by people, easy for models to follow. (How to Write a CLAUDE.md.)

Gotchas

No blank line before a list or heading can stop it rendering in some tools.
Underscores in words (snake_case_name) are sometimes treated as italics. Wrap code-like words in backticks.
Indentation matters for nested lists and code inside lists.
Special characters like *, #, and _ can be shown literally by putting a backslash in front: \*.

Where to write it

Any text editor works. VS Code shows a live preview with Ctrl/Cmd + Shift + V. (VS Code for Beginners.) GitHub previews .md files automatically.

EasySpawn workspaces keep your project's Markdown — README, CLAUDE.md, docs — alongside the code, so Claude Code reads the same instructions every session. See how it works or join the waitlist.