Markdown Tutorial: Learn Markdown in 10 Examples
A beginner-friendly, examples-first tutorial. Each lesson shows the Markdown you type next to the result you get — copy any example and try it yourself.
Markdown is a plain-text way to format documents: you type simple symbols like # heading, **bold**, and - list item, and they render as formatted text. It takes about 30 minutes to learn, and the ten lessons below cover everything most people ever use — each with a worked example you can copy.
What Is Markdown?
Markdown is a lightweight markup language created by John Gruber in 2004: you write plain text with a few intuitive symbols, and it converts to cleanly formatted HTML. It has become the standard way to write READMEs, documentation, notes, blog posts, and messages on GitHub, Reddit, Discord, Notion, Obsidian, and hundreds of other tools.
The best way to learn it is by example. Work through the ten lessons below in order — each one shows a realistic snippet of Markdown next to exactly what it renders as, plus a one-line rule to remember. Keep the live editor open in another tab and paste each example in as you go.
Lesson 1: Headings
Headings give your document structure. Start a line with one to six hash symbols followed by a space — one hash is the biggest heading, six is the smallest. Most documents only need the first three levels.
# Trip Report: Iceland ## Day 1 — Reykjavik ### What we ate
Rule: One # per heading level, always followed by a space: # is an H1, ## is an H2, up to ###### for an H6.
Lesson 2: Paragraphs & Line Breaks
Paragraphs are just text separated by a blank line. Pressing Enter once usually does not start a new line in the output — to force a line break inside a paragraph, end the line with two spaces (or a backslash).
This is the first paragraph. This is a second paragraph, separated by a blank line. This line was forced onto a new line with two trailing spaces.
This is the first paragraph.
This is a second paragraph, separated by a blank line.
This line was forced onto a new line with two trailing spaces.
Rule: A blank line starts a new paragraph; two spaces at the end of a line force a line break without one.
Lesson 3: Bold & Italic
Wrap text in asterisks to emphasize it: one asterisk on each side for italic, two for bold, three for both at once. Underscores work too, but asterisks are the safer habit because they work mid-word everywhere.
The deadline is **Friday at 5 pm** — please *do not* miss it. You can combine them for ***really important*** notes.
The deadline is Friday at 5 pm — please do not miss it.
You can combine them for really important notes.
Rule: One asterisk = *italic*, two = **bold**, three = ***bold italic***.
Lesson 4: Lists
Start each line with a dash (or asterisk) for a bulleted list, or a number and a period for a numbered list. Indent an item by two or more spaces to nest it under the one above.
Groceries: - Milk - Bread - Sourdough, if they have it - Eggs Recipe steps: 1. Preheat the oven to 200°C 2. Mix the dry ingredients 3. Bake for 25 minutes
Groceries:
- Milk
- Bread
- Sourdough, if they have it
- Eggs
Recipe steps:
- Preheat the oven to 200°C
- Mix the dry ingredients
- Bake for 25 minutes
Rule: Use - for bullets and 1. for numbered steps; indent with spaces to nest items.
Lesson 5: Links
A link has two parts: the visible text in square brackets, immediately followed by the URL in parentheses. The reader sees the text; clicking it opens the URL. An optional title in quotes shows as a tooltip.
Read the [Markdown cheat sheet](https://www.markdowntools.io/cheat-sheet) before the workshop.
Read the Markdown cheat sheet before the workshop.
Rule: Text in [square brackets], URL in (parentheses), with no space between them.
Lesson 6: Images
Images look exactly like links with an exclamation mark in front. The text in square brackets becomes the alt text — a description shown when the image cannot load and read aloud by screen readers, so make it meaningful.
The image renders here, with "A sunrise over the harbor" as its alt text.
Rule: An image is a link with a ! in front: .
Lesson 7: Blockquotes
Start a line with a greater-than sign to quote it. Repeat the > on every line of a multi-line quote (including blank lines between paragraphs) to keep the whole passage inside one quote block.
> Markdown is intended to be as easy-to-read > and easy-to-write as is feasible. > > — John Gruber
Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
— John Gruber
Rule: Start every quoted line with > and a space; keep the > on blank lines to continue the quote.
Lesson 8: Code
Wrap a short snippet in single backticks to show it inline in monospace. For whole blocks of code, put three backticks on the line before and after — and add a language name after the opening backticks for syntax highlighting.
Install it with `npm install`.
```js
function greet(name) {
return "Hello, " + name + "!";
}
```Install it with npm install.
function greet(name) {
return "Hello, " + name + "!";
}Rule: Single backticks for inline code; triple backticks (plus a language name) for code blocks.
Lesson 9: Tables
Build tables with pipes between columns. The first row is the header, the second row is a divider made of dashes, and every row after that is data. The pipes do not have to line up perfectly — but tidy source is easier to edit.
| Feature | Free plan | Pro plan | | -------- | --------- | --------- | | Projects | 3 | Unlimited | | Support | Email | Priority |
| Feature | Free plan | Pro plan |
|---|---|---|
| Projects | 3 | Unlimited |
| Support | Priority |
Rule: Pipes | separate columns; a row of dashes under the first row turns it into the header.
Lesson 10: Task Lists & Horizontal Rules
Two finishing touches. A task list is a bulleted list where each item starts with [ ] for an open checkbox or [x] for a done one — supported on GitHub and most modern apps. And three dashes alone on a line draw a horizontal rule to divide sections.
## Launch checklist - [x] Write the announcement post - [x] Update the changelog - [ ] Schedule the social posts --- Everything below the line is archive material.
- Write the announcement post
- Update the changelog
- Schedule the social posts
Everything below the line is archive material.
Rule: A list item with [ ] or [x] becomes a checkbox; three dashes (---) alone on a line draw a divider.
Deep dive: Markdown task lists → · Deep dive: Markdown horizontal rules →
Practice What You've Learned
The fastest way to make it stick: write a short document — a recipe, a to-do list, a meeting note — using at least five of the lessons above. The editor is free, runs in your browser with no signup, and autosaves as you type.
Try it in the live editor →Want a one-page summary to keep next to your keyboard? The Markdown cheat sheet condenses everything from this tutorial into a printable reference, including the extended syntax (footnotes, strikethrough, highlights) we skipped here.
Frequently Asked Questions
How long does it take to learn Markdown?
About 30 minutes for the basics. The ten lessons on this page cover everything most people ever use — headings, emphasis, lists, links, images, quotes, code, and tables. After an afternoon of practice in a live editor, the syntax becomes muscle memory.
Where is Markdown used?
Almost everywhere developers and writers work: GitHub and GitLab (READMEs, issues, pull requests), Reddit, Discord, Slack, Notion, Obsidian, Jupyter notebooks, static site generators like Hugo and Jekyll, and most documentation platforms. Some apps support a slightly different subset, but the core syntax is the same.
What is the difference between Markdown and HTML?
Both describe formatted documents, but Markdown is designed to be readable as plain text, while HTML uses tags like <strong> and <h1> that clutter the source. Markdown is converted to HTML when it is rendered, and most Markdown processors let you drop raw HTML into a document when you need something Markdown cannot express.
What app do I need to write Markdown?
None — any plain text editor works, from Notepad to VS Code. For instant feedback while you learn, use an editor with a live preview, like the free MarkdownTools editor in your browser, so you can see the rendered result as you type.
What file extension does a Markdown file use?
The standard extension is .md (for example README.md). You will also see .markdown, which is equivalent but less common. Both are plain text files you can open in any editor.
Do spaces and blank lines matter in Markdown?
Yes, in a few specific places. A blank line separates paragraphs, two trailing spaces force a line break, a space is required after heading hashes and list markers, and indenting a list item nests it. Otherwise Markdown is forgiving about whitespace.
Is Markdown free to use?
Completely. Markdown is an open plain-text format, not a product — there is nothing to buy, license, or install. Your files are ordinary text, so they open on any device and will still be readable decades from now.