If you've ever seen a file named README.md on GitHub, or noticed text with weird **stars** and # symbols, you've run into Markdown. This guide explains what it is, why people use it, and how to write it — in plain, simple terms.

Table of Contents

1. What Is Markdown?
2. Why Do People Use It?
3. Headings
4. Bold and Italic Text
5. Lists
6. Links
7. Images
8. Code
9. Blockquotes
10. Tables
11. Horizontal Line
12. Line Breaks (a Common Gotcha)
13. Where Markdown Is Used
14. Quick Summary

1. What Is Markdown?

Markdown is a simple way to format text using plain symbols, instead of clicking buttons like "Bold" or "Bullet List" in a word processor.

You type something like this:

# Hello World
This is **bold** and this is *italic*.

And it turns into this when it's rendered (displayed nicely):

Hello World

This is bold and this is italic.

The file itself is just a plain text file — nothing fancy — saved with a .md extension (short for "Markdown"). You can open it in Notepad, VS Code, or any text editor, and it'll still make sense even unformatted, because the symbols are simple and readable on their own.

2. Why Do People Use It?

• It's simple. You don't need any special software — just a text editor.
• It's readable even as plain text. A .md file looks fine even before it's turned into a nicely styled page.
• It's everywhere. GitHub, GitLab, Notion, Reddit, Discord, and countless apps understand Markdown.
• It's fast to write. No mouse clicks — just type symbols as you go.

That's why documentation files, blog posts (like this one!), and README files are almost always written in Markdown.

3. Headings

Use the # symbol to make headings. The number of # symbols controls the size — one # is the biggest heading, and it gets smaller from there.

# Heading 1 (biggest)
## Heading 2
### Heading 3
#### Heading 4 (smallest commonly used)

Renders as:

Heading 1 (biggest)

Heading 2

Heading 3

Heading 4 (smallest commonly used)

Tip: Always leave a space after the # symbols, or it won't work.

4. Bold and Italic Text

This is **bold text**.
This is *italic text*.
This is ***bold and italic***.

Renders as:

This is bold text.
This is italic text.
This is bold and italic.

You can also use __double underscores__ for bold and _single underscores_ for italic — they work the same way. Most people stick to asterisks (*) since it's more common.

5. Lists

Bullet list — use a dash, star, or plus sign:

- Apples
- Bananas
- Oranges

Renders as:

• Apples
• Bananas
• Oranges

Numbered list — use numbers followed by a period:

1. Wake up
2. Make coffee
3. Write code

Renders as:

1. Wake up
2. Make coffee
3. Write code

Tip: You don't need to get the numbers exactly right — Markdown will re-number them for you automatically. Typing 1. three times in a row still produces 1, 2, 3.

6. Links

[Click here to visit Google](https://www.google.com)

Renders as:

Click here to visit Google

The pattern is always: square brackets for the text people see, then parentheses right after for the actual web address — no space in between.

[text people see](https://the-actual-link.com)

7. Images

Images work almost exactly like links, but with an ! in front:

![A cute dog](https://example.com/dog.jpg)

The text inside the square brackets (A cute dog) is the "alt text" — a short description shown if the image can't load, and used by screen readers for accessibility.

8. Code

Inline code (for a single word or short snippet) — wrap it in single backticks:

Use the `console.log()` function to print something.

Renders as:

Use the console.log() function to print something.

Code blocks (for multiple lines of code) — wrap the whole block in three backticks, with the language name right after the first set of backticks:

```javascript
function greet(name) {
  console.log("Hello, " + name);
}
```

Renders as:

function greet(name) {
  console.log("Hello, " + name);
}

Adding the language name (like javascript, python, or html) after the first three backticks tells Markdown to add color-coded syntax highlighting.

9. Blockquotes

Use > at the start of a line to quote something:

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

Renders as:

This is a quote.
It can span multiple lines.

This is commonly used to highlight a note, a quote from someone, or a warning.

10. Tables

Tables use pipes (|) to separate columns and dashes (-) to separate the header row from the data:

| Name  | Age | City     |
|-------|-----|----------|
| Sam   | 25  | Boston   |
| Alex  | 30  | New York |

Renders as:

Tip: The dashes don't need to line up perfectly — even |-|-|-| works. Markdown figures out the columns from the pipes.

11. Horizontal Line

Three or more dashes (or asterisks) on their own line create a horizontal divider:

---

Renders as a line separating sections — useful for splitting up parts of a long document (you've seen several of these already in this post).

12. Line Breaks (a Common Gotcha)

This trips up almost everyone starting out: pressing Enter once in Markdown does not create a new line when rendered.

This is line one.
This is line two.

Renders as:

This is line one.
This is line two.

(They get squished onto one line!)

To force a real line break, either:

• Leave a completely empty line between them (this starts a new paragraph), or
• Add two spaces at the end of a line before pressing Enter.

This is line one.

This is line two.

This renders as two separate paragraphs, properly spaced apart.

13. Where Markdown Is Used

• GitHub / GitLab — README files, issues, pull request descriptions
• Documentation sites — many docs are written and generated from .md files
• Note-taking apps — Notion, Obsidian, and many others support Markdown
• Chat apps — Discord and Slack use a simplified version of Markdown for bold/italic/code formatting
• Blogging platforms — many static site generators (like Jekyll or Hugo) build entire websites from .md files

14. Quick Summary

```code```

| Code block |
| > Text | Blockquote |
| \| col \| col \| | Table |
| --- | Horizontal line |

The big idea: Markdown lets you format text using a handful of simple, memorable symbols — no toolbar, no mouse, no fuss. Once you learn the dozen or so symbols in the table above, you can write clean, formatted documents anywhere Markdown is supported.