Skip to main content

Markdown Crash Course

Throughout this guide, you'll see examples written in Markdown — a simple way to format text using plain symbols instead of complicated buttons or menus.

If you've never seen Markdown before, don't worry. It's designed to be readable even in its raw form. This page will teach you everything you need to understand the examples in this guide.

What Is Markdown?​

Markdown is a way to write formatted text using only your keyboard. Instead of clicking "Bold" in a toolbar, you type **bold**. Instead of clicking a "Heading" dropdown, you type ## Heading.

The key insight: Markdown files are plain text files (.md). You can write them in any text editor — Notepad, TextEdit, VS Code, or even your notes app.

The Only Things You Need to Know​

Here are the Markdown features used in this guide's examples. That's all you need.

Headings​

Headings are created with # symbols. The more # symbols, the smaller the heading.

# Big Heading (like a chapter title)
## Medium Heading (like a section title)
### Small Heading (like a subsection)

In this guide: You'll see ## and ### used to organize requirements and tasks.

Bullet Lists​

Start a line with - or * to make a bullet point.

- Item one
- Item two
- Item three

In this guide: Bullet lists are used to list requirements, features, and rules.

Checkboxes (Task Lists)​

Add [ ] or [x] after the - to make a checklist.

- [ ] Not done yet
- [x] Already completed
- [ ] Another task to do

In this guide: Checklists are used to track tasks and requirements.

Bold and Italic​

**bold text** — wrap with two asterisks
*italic text* — wrap with one asterisk

In this guide: Bold is used for emphasis. Italic is used rarely.

Code Blocks​

When you see text wrapped in triple backticks like this:

```markdown
Some example text here
```

That's a code block. It means "this is an example you can copy and use." The word after the opening backticks (like markdown) just tells the computer what language it is — you don't need to type it.

In this guide: Code blocks show you templates and examples you can copy into your own documents.

Inline Code​

Use single backticks for short pieces of code or file names within a sentence:

Save your file as `requirements.md`

In this guide: Inline code is used for file names and short technical terms.

Horizontal Lines​

Three dashes create a line across the page:

---

In this guide: Horizontal lines separate different sections.

[Link text](https://example.com)

In this guide: Links connect you to related topics and resources.

A Real Example​

Here's what a simple requirements document looks like in Markdown:

## Login System Requirements

### What It Should Do
- Users can create an account with email and password
- Users can log in with their email and password
- Users can reset their password if they forget it

### Security Rules
- [ ] Passwords must be at least 8 characters
- [ ] Lock account after 5 failed attempts
- [ ] Log out inactive users after 24 hours

See how readable it is? Even without knowing Markdown, you can probably understand what this document is saying. That's the whole point.

How to Write Markdown​

You don't need any special software. Here are your options:

MethodWhat to Do
VS CodeCreate a new file with .md extension (like requirements.md). Start typing.
CursorSame as VS Code — create a .md file and start typing.
Any text editorNotepad, TextEdit, or any basic editor works. Save as .md.
AI toolsAsk your AI to "write this as a markdown file" and it will format it for you.

Pro tip: Most AI coding tools understand Markdown natively. If you write your requirements in Markdown and save them as .md files, the AI can read them directly.

Quick Reference Card​

What You WantType This
Big heading# Text
Section heading## Text
Subsection### Text
Bullet point- Text
Checklist item (unchecked)- [ ] Text
Checklist item (checked)- [x] Text
Bold**text**
Italic*text*
Code block``` before and after
Inline code`text`
Horizontal line---
Link[text](url)

That's It​

You now know enough Markdown to read and write every example in this guide. There's nothing else to learn — the rest is just practice.

Markdown is not code. It's just a way to write plain text that happens to be very good at organizing information. If you can write an email, you can write Markdown.

Last updated on