Markdown: the writing format developers use

Markdown is a way to write formatted text using plain characters. Asterisks for bold. Hashes for headings. Dashes for lists. It looks almost like the formatting you'd use in a quick email or a Slack message — except programs know how to render it as proper headings, bullets, and links.

It's worth a short lesson because almost everything in the Claude Code world is written in Markdown:

README.md — the front page of nearly every project.
CLAUDE.md— the file you write to teach Claude about your project (you'll meet this in Module 3).
Almost every documentation site, blog post, and GitHub issue.

The cheat sheet

That's really all you need. The whole syntax:

markdown

# A big heading
## A smaller heading
### A smaller one still

A paragraph is just normal text. To force a paragraph break,
leave a blank line between blocks.

**bold text** and *italic text* and `inline code`.

- A bullet list
- Another bullet
- A third bullet, with a [link](https://zerotoclaude.com)

1. Numbered lists
2. work the same way
3. but start each line with a number

> A blockquote — useful for callouts.

```python
# A fenced code block
print("Hello")
```

A horizontal rule:

---

That's basically it.

Anything that looks like normal text in the source is rendered as normal text. Anything with the special characters becomes formatted. That's the whole language.

Note

There are a few flavours of Markdown — GitHub adds task lists with checkboxes, tables, and a few extras. CommonMark is the more strict standard. The basics are the same everywhere; you'll only bump into the differences in edge cases.

Where you'll see it rendered

Markdown is rendered automatically in:

GitHub — any .md file in a repo is shown as a rendered page when you open it on the website.
VS Code — open any .md file and press Ctrl/Cmd + Shift + V to see the rendered preview side by side.
Claude Code— Claude reads and writes Markdown fluently. When it shows you a plan or a summary, it's often using Markdown formatting that the terminal renders inline.
Documentation tools— Mintlify, Docusaurus, MkDocs, this very site you're reading. Markdown is the source.

A real example: a starter README

Here's what a tiny but complete README.md for a project might look like:

markdown

# vacation-photo-renamer

A tiny script for renaming a folder of photos with sortable numeric
prefixes (`001-foo.jpg`, `002-bar.jpg`, ...).

## Install

Requires Python 3.10+. No dependencies to install.

## Use

```bash
python rename.py path/to/photos
```

## License

MIT.

Short. Says what the thing is, how to install it, how to use it. Many open-source projects have million-line READMEs, but most really just need this much to be useful.

Write Markdown for skim-readers

Anyone who reads documentation is usually scrolling fast, looking for one specific answer. Use headings, short paragraphs, and lists liberally. A wall of unbroken prose is harder to scan than the same information chunked into sections.

Markdown is the default lingua franca

When you write a CLAUDE.md for your project, when you write a slash command for Claude Code, when you contribute to an open-source README, when you publish a blog post on most modern platforms — Markdown is the format. Learning it once pays back forever.

What to take with you

Markdown is plain text with a few special characters for formatting: # for headings, ** for bold, - for lists, backticks for code.
It's rendered automatically in GitHub, VS Code, Claude Code, and almost every documentation tool.
Useful project files written in Markdown: README.md, CLAUDE.md, contribution guides, changelogs.
Write for skim-readers — short sections, lists, clear headings.