Markdown Tutorial: Learn Markdown in 15 Minutes

This markdown tutorial teaches you the whole language through ten short exercises you type into a live editor. By the end you'll have written headings, lists, links, images, code, tables and a checklist, and you'll know which syntax works on GitHub, Reddit and Slack. No installs, no prior experience needed.

How Hard Is It to Learn Markdown?

Not hard at all. Markdown has roughly a dozen rules, and most of them mirror habits you already have in plain-text email: asterisks for emphasis, dashes for bullets, blank lines between paragraphs. John Gruber published the original syntax in December 2004 with exactly that goal, and the format hasn't grown much since.

Most markdown tutorial sites split the lessons across a dozen pages. This one keeps everything on a single page so you can scroll back to any exercise. If you're new to the idea itself, read what Markdown is and why it exists first. This page assumes you know the concept and want to learn Markdown by doing. Budget 15 minutes for the ten exercises, and keep the editor open in another tab so you can see every keystroke render.

You need a browser and nothing else. Open the free Markdown editor, clear the sample text, and type each exercise on the left. The rendered preview on the right updates as you type, which is the fastest feedback loop for learning how to use Markdown.

If you'd rather work locally, VS Code previews Markdown out of the box with Ctrl+Shift+V, and Obsidian renders as you type. The exercises are identical in all three. We recommend the browser editor for the first pass because there's nothing to configure and the preview sits right beside the source.

Two habits will save you time. First, leave a blank line between blocks (a heading, a paragraph, a list). Second, when something looks wrong, check spacing before anything else. Almost every beginner bug is a missing space or a missing blank line.

Exercises 1 to 5: Markdown Basics

Each exercise shows the syntax, then what it renders as. Type it, don't paste it. Writing Markdown by hand builds the muscle memory that pasting skips.

Exercise 1: Headings

Start a line with one to six # characters, then a space, then the text.

# Trip Report
## Day One
### Morning

Renders as a large title, a section heading and a subsection heading. The space after the # is required in CommonMark 0.31.2, so #Title stays plain text.

Exercise 2: Paragraphs and Line Breaks

Separate paragraphs with a blank line. To break a line inside a paragraph, end it with two spaces or a backslash.

First paragraph.

Second paragraph, line one.\
Line two of the same paragraph.

The backslash form is easier to see than trailing spaces, so we prefer it. Both are in the CommonMark spec under hard line breaks.

Exercise 3: Emphasis

Wrap text in one asterisk for italic, two for bold, three for both.

*italic*, **bold**, ***bold italic***

Underscores work the same way inside a sentence. Asterisks are safer in words like snake_case_names, where underscores are literal.

Exercise 4: Lists

Bullets start with -, * or +. Numbered lists start with a number and a period. Indent nested items by two to four spaces.

- Pack passport
- Pack charger
  - USB-C cable
1. Book flight
2. Book hotel

Renders as a bulleted list with a nested item, then a numbered list. One detail trips people up: the first number sets where the list starts, so a list beginning with 4. renders as 4, 5, 6.

Exercise 5: Links

Put the link text in square brackets and the URL in parentheses right after it.

Read the [CommonMark spec](https://spec.commonmark.org/) for details.
Or paste a bare URL in angle brackets: <https://commonmark.org>

Both forms render as clickable links. Our Markdown links guide covers titles, reference links and anchors if you need more.

Try the Exercises in the Editor

Paste this into the editor, then edit each line until the preview matches what you expect. Every markdown tutorial exercise from the first half is in here. Then delete it and rebuild the same document from memory. That second pass is where the syntax sticks.

Exercises 6 to 10: Writing in Markdown for Real Documents

The second half adds the blocks you'll use in READMEs, notes and docs. Two of them (tables and task lists) come from GitHub Flavored Markdown rather than core CommonMark, which matters in the next section.

Exercise 6: Images

An image is a link with an exclamation mark in front. The bracket text becomes the alt text.

![Sunset over the harbour](https://example.com/sunset.jpg)

Renders as the picture itself, with the alt text shown if the file fails to load. Relative paths such as images/sunset.jpg work on GitHub and in static site generators, but in a browser editor you need a full URL. The image guide covers sizing and captions, which core Markdown doesn't handle.

Exercise 7: Code

Use single backticks for inline code and a fence of three backticks for a block. Add a language name after the opening fence for syntax highlighting.

Run `npm install` first.

```js
console.log("hello");
```

Renders as monospace text inline and as a highlighted block below. The outer fence in this example uses four backticks so the inner three-backtick fence stays literal, which is the trick for showing Markdown inside Markdown.

Exercise 8: Blockquotes and Horizontal Rules

Start a line with > to quote it. Three dashes on their own line draw a horizontal rule.

> Simplicity is the goal.

---

Renders as an indented quote with a left border, then a thin line. Quotes can nest with >> and can contain lists or code, which is handy for pasting an email thread into notes.

Exercise 9: Tables

Pipes separate cells, and a row of dashes separates the header. A colon on the right of the dashes right-aligns that column.

| Item | Price |
|------|------:|
| Tea  |  3.50 |
| Cake |  4.00 |

Renders as a two-column table with the prices right-aligned. The cell padding doesn't matter, so you can write the pipes tightly and let a table generator tidy them later.

Exercise 10: Task Lists

A bullet followed by [ ] or [x] becomes a checkbox.

- [x] Learn headings
- [ ] Write a README

Renders as one ticked and one empty checkbox. On GitHub the boxes are clickable in issues and pull requests, and the click edits the underlying text for you.

When you've finished all ten, you have a complete document with every block type you need for everyday markdown writing. Bookmark the Markdown cheat sheet as your reference from here on.

Which Markdown Flavor Are You Writing In?

This is the question most markdown tutorial pages skip, and it causes the most confusion once you leave the editor. CommonMark defines the core: headings, emphasis, lists, links, images, code, blockquotes and rules. The GFM spec adds tables, task lists, strikethrough and bare URL autolinks as extensions.

So exercises 1 to 8 work almost everywhere. Exercises 9 and 10 work on GitHub, GitLab, Obsidian, Notion and in our editor, but not in every renderer. A few platform notes from our testing:

• GitHub renders all ten exercises in README files, issues and pull requests.
• Reddit supports the basics plus tables, but not task lists.
• Slack uses its own mrkdwn dialect: single asterisks mean bold, and headings don't render at all.
• Discord handles emphasis, code, blockquotes and three heading levels, but not tables.

The limitation to accept: Markdown has no standard way to set colour, font size or column layout. When you need those, you drop to HTML, and our Markdown vs HTML comparison explains when that trade is worth it.

Common Mistakes When You Write in Markdown

No space after the hash. #Heading renders as literal text. Write # Heading.

No blank line before a list. In some renderers a list that directly follows a paragraph is swallowed into that paragraph. Put a blank line above it.

Single newline expected to break the line. In CommonMark a lone newline is folded into the paragraph. Use a backslash or two trailing spaces, or read our line break guide for the four options.

What are the disadvantages of using Markdown? Three honest ones. Layout control is minimal: no columns, no exact spacing, no fonts. Flavors differ, so a document that renders on GitHub can look different in an email client or a wiki. And there's no built-in way to embed interactive elements beyond what the host platform adds.

Against that, files stay readable as plain text forever, they diff cleanly in Git, and every major tool from VS Code to Obsidian to ChatGPT reads them. If you're curious why AI assistants answer in this format, see why ChatGPT uses Markdown.

Markdown Tutorial FAQ

That's the whole markdown tutorial: ten exercises, one flavor caveat, three mistakes to avoid. The syntax you learned here covers nearly everything you'll type in a README, a wiki page or a set of notes. Keep practising in the editor, where the preview shows you the result of every keystroke, and reach for the cheat sheet whenever a rarer block comes up.