How to Write Markdown — Beginner Tutorial With Live Practice

Markdown is a lightweight writing format that uses plain-text symbols to create formatted output. A single asterisk makes text italic. Two asterisks make it bold. A hash sign creates a heading. The idea is that the plain text should look readable even before it is rendered. This tutorial covers the 10 syntax patterns you need to write any markdown document — and you can practice each one in the free live editor as you read.

What Markdown Is and Why It Is Worth Learning

Markdown was created in 2004 by John Gruber as a simple way to write for the web without writing raw HTML. Today it is used everywhere:

• GitHub README files and comments
• Documentation sites (Docs, Wikis, GitBook)
• Static site generators (Jekyll, Hugo, Eleventy)
• Note-taking apps (Obsidian, Notion, Bear)
• Forums and chat tools (Reddit, Discord, Slack)
• Blog platforms (Ghost, Hashnode, Dev.to)

Learning markdown takes about 30 minutes. Once you know it, you never forget it — the syntax is intuitive enough that most people remember it without a reference sheet after using it a few times.

Text Formatting — Bold, Italic, Strikethrough, Code

These four patterns handle the vast majority of text emphasis needs:

What you type	What you get
**bold text**	bold text
*italic text*	italic text
~~strikethrough~~	strikethrough
`inline code`	inline code

You can combine them: **_bold and italic_** gives you bold italic. In a live editor, selecting text and clicking a toolbar button wraps it automatically — you do not need to type the symbols by hand if you prefer clicking.

Headings — Creating Document Structure

Headings use the hash symbol (#). The number of hashes sets the heading level:

# Heading 1 — the page title
## Heading 2 — major sections
### Heading 3 — subsections
#### Heading 4 — rarely needed

Always leave a space between the hash and the text: # My Title not #My Title. Most markdown parsers require the space.

Best practice: use a single H1 per document (the page title), and use H2 for all major sections. Going deeper than H3 usually signals that the content needs to be split into separate documents.

Sell Custom Apparel — We Handle Printing & Free Shipping

Lists — Ordered, Unordered, and Task Lists

Unordered list (bullet points) — use a dash or asterisk:

- First item
- Second item
  - Nested item (two spaces before the dash)

Ordered list — use numbers followed by a period:

1. First step
2. Second step
3. Third step

You can use 1. for every line — the markdown parser will number them correctly. Some writers do this so inserting a new step does not require renumbering everything.

Task list — checkboxes for to-do items:

- [x] Completed task
- [ ] Incomplete task

Task lists render as checkboxes in GitHub, Notion, and many other tools. In a live preview editor, you can see exactly how they will look.

Links, Images, and Tables

Links use bracket-then-parenthesis syntax: [link text](https://example.com)

Images use the same syntax with an exclamation mark prefix: ![alt text](image-url.jpg)

Tables use pipe characters to define columns:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell     | Cell     | Cell     |

The second row (dashes separated by pipes) is the header separator — it is required. You do not need to perfectly align the pipes; most parsers handle uneven spacing. In a live editor, the table renders in real time so you can see and fix alignment issues immediately.

Code Blocks and Blockquotes

Fenced code blocks use triple backticks. Add a language name after the opening backticks for syntax highlighting:

```javascript
const greeting = "Hello, world";
console.log(greeting);
```

Blockquotes use the greater-than sign:

> This is a blockquote.
> It can span multiple lines.

Nested blockquotes use >>. Blockquotes are useful for citing sources, callout notes, or highlighting important statements in documentation.

Frequently Asked Questions

How long does it take to learn markdown?

Most people are comfortable with the core syntax in 20-30 minutes of practice. The ten patterns in this tutorial cover nearly everything you will write in daily use.

How do I write a heading in markdown?

Use the hash symbol followed by a space and your heading text. One hash for H1, two for H2, three for H3. Example: ## My Section Title

How do I add a link in markdown?

Use square brackets for the link text, followed immediately by parentheses containing the URL: [click here](https://example.com)

Can I practice markdown without installing anything?

Yes. Open the free WildandFree Markdown Editor in your browser. Type markdown on the left and see the formatted output on the right, instantly, with no download required.