The Big Picture

Before learning syntax, understand what problem Markdown actually solves.

Sound familiar?

You save Report.docx, then Report_v2.docx, then Report_FINAL.docx. Copy formatted text into an email and the layout breaks. Click Bold, click Heading, hunt for toolbar buttons — and the file only works in that one app.

Markdown lets you format text using plain characters you type directly.
Write # Heading instead of clicking "Heading 1." Write **bold** instead of selecting text and clicking Bold.

Plain text — open any .md file in any editor and read it immediately
Portable — formatting travels with the file, not locked in one app
Fast — your hands never leave the keyboard
Universal — GitHub, Obsidian, Slack, Discord, and hundreds more
Forgiving — small mistakes usually still render fine

The Typewriter Analogy

A blank sheet of paper→A .md text file

ALL CAPS for a title→# Heading

Underlining for emphasis→**bold** or *italic*

Indenting a bullet list→- item

Writing "see page 42"→[link text](url)

A sticky note in the margin→> blockquote

Key Terms

Plain English definitions — no dictionary required.

Markdown

A lightweight markup language — add simple characters to plain text to describe formatting.

.md file

A text file with the .md extension. Same as .txt but signals Markdown formatting.

Syntax

The specific characters Markdown recognizes — # for headings, ** for bold.

Render / Preview

Converting raw Markdown into formatted output — big headings, clickable links, bold text.

Flavor / Variant

Different apps extend Markdown slightly. GitHub adds tables; Obsidian adds wikilinks.

Fenced code block

Multi-line code surrounded by triple backticks ``` — the standard way to include code.

What Is a .md File?

Nothing magic — just a text file with a special extension.

A Markdown file is just a text file. Create one in any editor, save with .md, open in a Markdown-aware app for live preview.

What you type

# My Project

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

- Easy to learn

- Works everywhere

What it renders as

My Project

This is bold and italic.

Easy to learn
Works everywhere

The raw file always stays readable. Even if preview breaks, you can still read the content.

Headings & Paragraphs

Structure your document like chapter titles and section headers.

Headings

# Heading 1 — largest (document title)
## Heading 2 — major sections
### Heading 3 — subsections
#### Heading 4

Separate paragraphs with a blank line:

This is the first paragraph.

This is the second paragraph.

Put a space after the # symbols. #Heading may not work in all apps. Always write # Heading.

Bold, Italic & More

What you type

**bold**
*italic*
***bold and italic***
~~strikethrough~~

What you get

bold
italic
bold and italic
~~strikethrough~~

Pick one style and stick with it. Most people use asterisks (**bold**, *italic*) rather than underscores.

Lists

Bullet & numbered lists

# Unordered (bullets)
- First item
- Second item
  - Nested item (indent 2 spaces)

# Ordered (numbers)
1. First step
2. Second step
3. Third step

Links

Link syntax

# Basic link
[GitHub beginner guide](https://goaspi.com/101/github/)

# Reference-style (cleaner for long docs)
Check out [GitHub][gh] and [Obsidian][obs].

[gh]: https://github.com
[obs]: https://obsidian.md

# Obsidian wikilinks (Obsidian only)
[[Note Title]]
[[Note Title|Custom display text]]

Images

Image syntax

# Basic image
![alt text describing the image](https://example.com/image.png)

# Image that is also a link
[![Click this image](thumbnail.png)](https://example.com)

Alt text describes the image for screen readers and when the image fails to load. Always include it.

Code & Code Blocks

Inline & fenced code

# Inline code (within a sentence)
Use the `git status` command to see what changed.

# Fenced code block (multi-line)
```bash
git clone https://github.com/user/repo.git
cd repo
git status
```

# Add language name for syntax highlighting
```python
def greet(name):
    print(f"Hello, {name}!")
```

Blockquotes & Callouts

Blockquotes

> This is a quoted passage.
> It can span multiple lines.
>
> — Attribution optional

Obsidian callouts (Obsidian only)

Callout boxes

> [!NOTE]
> Useful information the reader should know.

> [!TIP]
> Helpful advice.

> [!WARNING]
> Something to watch out for.

Tables

Part of GitHub Flavored Markdown — works in GitHub, Obsidian, and most modern editors.

Table syntax

| Column A | Column B | Column C |
|----------|----------|----------|
| Row 1    | Data     | More     |
| Row 2    | Data     | More     |

# Alignment: :--- left, :---: center, ---: right
| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| aligned  | aligned  | aligned  |

Task Lists

Checkboxes

- [ ] Unchecked task
- [x] Completed task
- [ ] Another thing to do

The space inside brackets matters: [ ] not [].

Where You'll Use Markdown

🐙

GitHub

READMEs, issues, PRs

💎

Obsidian

Every note in your vault

⌨️

Cursor / VS Code

Docs & project notes

💬

Slack / Discord

Quick message formatting

📝

Static sites

Blogs via Eleventy, Hugo

📖

This guide

You're reading MD now

Continue learning: GitHub guide (where .md files live in repos) · Obsidian guide (Markdown-powered linked notes)

GitHub vs. Obsidian

Not all Markdown is identical — here's what differs.

Feature	Standard MD	GitHub (GFM)	Obsidian
Headings, bold, lists	Yes	Yes	Yes
Tables	Sometimes	Yes	Yes
Task lists `- [ ]`	No	Yes	Yes
Strikethrough `~~`	No	Yes	Yes
Wikilinks `[[note]]`	No	No	Yes
Callouts `> [!NOTE]`	No	No	Yes

Rule of thumb: Stick to standard syntax and your files work everywhere. Add Obsidian-specific features only in Obsidian vaults.

Common Mistakes

Mistake	What happens	Fix
No space after `#`	Heading doesn't render	Write `# Heading`
Missing blank line before list	List merges into paragraph	Add blank line before `- item`
Unclosed `**` or backtick	Formatting runs to end of file	Count opening and closing markers
Broken link syntax	Raw text shows instead of link	Check: `[text](url)`
Pasting from Word	Hidden formatting garbage	Paste as plain text, re-add MD
Huge tables	Painful to edit by hand	Link to a spreadsheet instead

Markdown vs. Other Formats

Format	What it is	When to use it
Markdown (.md)	Plain text with formatting characters	Notes, docs, READMEs, Git/Obsidian
Word (.docx)	Proprietary rich document	Formal reports, track changes
Google Docs	Cloud word processor	Real-time collaboration on prose
HTML (.html)	Web page markup	Published websites, precise layout
PDF	Fixed-layout final output	Sharing finished, uneditable docs

Cheat Sheet

Essential syntax

# Heading 1
## Heading 2
### Heading 3

Regular paragraph. Blank line between paragraphs.

**bold**  *italic*  ~~strikethrough~~  `inline code`

- Bullet item
  - Nested bullet
1. Numbered item

- [ ] Task unchecked
- [x] Task done

[Link text](https://url.com)
![Alt text](image.png)

> Blockquote

| Col 1 | Col 2 |
|-------|-------|
| data  | data  |

---
Horizontal rule

Glossary

Term	Definition
Markdown	Plain-text formatting syntax using #, *, -, etc.
.md file	A text file containing Markdown content
Render	Convert raw Markdown into formatted visual output
GFM	GitHub Flavored Markdown — adds tables, task lists, strikethrough
Wikilink	Obsidian-style link: [[Note Title]]
Fenced code block	Multi-line code surrounded by triple backticks
Blockquote	Quoted text starting with >
Alt text	Image description for accessibility
Flavor	An app's specific extensions to standard Markdown
CommonMark	A standardized specification of core Markdown syntax