# Markdown for Complete Beginners

A practical guide to understanding and writing Markdown — written for someone who has never used plain-text formatting before.

---

## Table of Contents

1. [The Big Picture](#the-big-picture)
2. [Key Terms (Plain English)](#key-terms-plain-english)
3. [What Is a .md File?](#what-is-a-md-file)
4. [Headings and Paragraphs](#headings-and-paragraphs)
5. [Emphasis: Bold, Italic, and More](#emphasis-bold-italic-and-more)
6. [Lists](#lists)
7. [Links](#links)
8. [Images](#images)
9. [Code and Code Blocks](#code-and-code-blocks)
10. [Blockquotes and Callouts](#blockquotes-and-callouts)
11. [Tables](#tables)
12. [Horizontal Rules and Line Breaks](#horizontal-rules-and-line-breaks)
13. [Task Lists (Checkboxes)](#task-lists-checkboxes)
14. [Where You'll Use Markdown](#where-youll-use-markdown)
15. [Markdown Flavors (GitHub vs. Obsidian)](#markdown-flavors-github-vs-obsidian)
16. [Common Mistakes and How to Avoid Them](#common-mistakes-and-how-to-avoid-them)
17. [Markdown vs. Other Formats](#markdown-vs-other-formats)
18. [Quick Reference Cheat Sheet](#quick-reference-cheat-sheet)
19. [Glossary](#glossary)

---

## The Big Picture

### What problem does Markdown solve?

Most writing tools lock your formatting inside a proprietary file. Open a `.docx` in a text editor and you see gibberish. Copy formatted text from a website into an email and the layout breaks. You end up clicking toolbar buttons for bold, headings, and lists — and the result only works in that one app.

**Markdown** is a simple way to format text using plain characters you type directly. You write `# Heading` instead of hunting for a "Heading 1" button. You write `**bold**` instead of selecting text and clicking Bold. The file stays readable even without any special app — and every tool that supports Markdown renders it beautifully.

It is designed for:

- **Notes and documentation** — README files, wikis, personal knowledge bases
- **Long-form writing** — blog posts, books, guides (like this one)
- **Technical content** — code snippets, API docs, project specs
- **Anywhere plain text lives** — GitHub, Obsidian, Slack, Discord, Notion, and hundreds more

### The typewriter analogy

| Real world | Markdown equivalent |
|---|---|
| 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` or `* item` |
| Writing "see page 42" | `[link text](url)` |
| A sticky note in the margin | `> blockquote` |
| Handwritten code on scratch paper | `` `inline code` `` or fenced code blocks |

### What makes Markdown different

1. **It is plain text** — open any `.md` file in Notepad, TextEdit, or VS Code and read it immediately.
2. **It is portable** — your formatting travels with the file, not locked in one app.
3. **It is fast** — your hands never leave the keyboard to hunt for toolbar buttons.
4. **It is universal** — GitHub, Obsidian, Slack, Reddit, Stack Overflow, and most developer tools speak Markdown.
5. **It is forgiving** — small syntax mistakes usually still render fine; you do not need perfection to get started.

---

## Key Terms (Plain English)

### Markdown
A lightweight markup language created by John Gruber in 2004. "Markup" means adding simple characters to plain text to describe formatting.

### .md file
A text file with the `.md` extension. Same as `.txt` but signals "this file uses Markdown formatting." Also sometimes `.markdown`.

### Syntax
The specific characters and patterns Markdown recognizes — like `#` for headings or `**` for bold.

### Render / Preview
Converting raw Markdown text into formatted output (headings look big, bold looks bold, links become clickable). Most editors show a live preview as you type.

### Flavor / Variant
Different apps extend Markdown slightly. GitHub Flavored Markdown (GFM) adds tables and task lists. Obsidian adds wikilinks `[[like this]]`. The core syntax is the same everywhere.

### Frontmatter
Optional metadata at the top of a file, wrapped in `---` lines. Used for titles, dates, tags. Common in Obsidian, Jekyll, and Hugo.

### Fenced code block
A block of code surrounded by triple backticks ` ``` `. The standard way to include multi-line code.

### Inline code
Short code snippets wrapped in single backticks `` `like this` `` within a sentence.

---

## What Is a .md File?

A Markdown file is just a text file. Nothing magic.

```
my-notes.md
README.md
project-guide.md
```

You can create one by:

1. **Any text editor** — TextEdit (set to plain text), Notepad, VS Code, Cursor, Obsidian
2. **Save with `.md` extension** — File → Save As → `filename.md`
3. **Open in a Markdown-aware app** — for live preview and nice formatting

### What you see vs. what you get

**What you type (source):**

```markdown
# My Project

This is a **bold** statement about *Markdown*.

- Easy to learn
- Works everywhere
```

**What it renders as:**

> # My Project
>
> This is a **bold** statement about *Markdown*.
>
> - Easy to learn
> - Works everywhere

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

---

## Headings and Paragraphs

Headings create document structure — like chapter titles and section headers.

### Syntax

```markdown
# Heading 1 — largest (use once per document, usually the title)
## Heading 2 — major sections
### Heading 3 — subsections
#### Heading 4
##### Heading 5
###### Heading 6 — smallest
```

**Important:** Put a space after the `#` symbols. `#Heading` may not work in all apps.

### Paragraphs

Separate paragraphs with a **blank line**:

```markdown
This is the first paragraph.

This is the second paragraph. The blank line between them tells Markdown to start a new paragraph.
```

Do not indent paragraphs (unless you are inside a list or blockquote). Just use blank lines.

---

## Emphasis: Bold, Italic, and More

### Bold

```markdown
**This is bold**
__This is also bold__
```

Renders as: **This is bold**

### Italic

```markdown
*This is italic*
_This is also italic_
```

Renders as: *This is italic*

### Bold and italic together

```markdown
***bold and italic***
**_bold and italic_**
```

### Strikethrough (GFM / many apps)

```markdown
~~crossed out text~~
```

Renders as: ~~crossed out text~~

### Tip

Pick one style and stick with it. Most people use `**bold**` and `*italic*` (asterisks) rather than underscores, because underscores appear in filenames and URLs.

---

## Lists

### Unordered (bullet) lists

Use `-`, `*`, or `+` — they all work the same:

```markdown
- First item
- Second item
- Third item
  - Nested item (indent with 2 spaces)
  - Another nested item
```

### Ordered (numbered) lists

```markdown
1. First step
2. Second step
3. Third step
   1. Nested numbered item
   2. Another nested item
```

**Note:** You can actually write `1.` for every item and Markdown auto-numbers them. But writing the correct numbers makes the source file easier to read.

### Mixing lists

```markdown
1. Gather ingredients
   - Flour
   - Eggs
   - Milk
2. Mix and bake
```

---

## Links

### Basic links

```markdown
[text that people click](https://example.com)
```

Example:

```markdown
Read the [GitHub beginner guide](https://goaspi.com/101/github/).
```

### Links with titles (tooltip on hover)

```markdown
[Obsidian](https://obsidian.md "A note-taking app")
```

### Automatic links

Most renderers turn bare URLs into clickable links:

```markdown
Visit https://goaspi.com for more guides.
```

### Reference-style links (cleaner for long documents)

```markdown
Check out [GitHub][gh] and [Obsidian][obs].

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

The link definitions can go at the bottom of the document, keeping paragraphs uncluttered.

### Obsidian wikilinks (Obsidian only)

```markdown
[[Note Title]]
[[Note Title|Custom display text]]
[[Note Title#Heading Name]]
```

These are not standard Markdown — they are an Obsidian extension. See the [[obsidian-for-beginners|Obsidian guide]] for details.

---

## Images

### Basic image syntax

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

- **Alt text** — describes the image for screen readers and when the image fails to load
- **URL** — link to the image file (can be web URL or local path)

### Images with titles

```markdown
![A calm lake at sunset](lake.jpg "Sunset over Lake Michigan")
```

### Images that are also links

```markdown
[![Click this image](thumbnail.png)](https://example.com/full-page)
```

### Local vs. hosted images

| Approach | Example | Best for |
|---|---|---|
| Web URL | `![logo](https://site.com/logo.png)` | GitHub READMEs, web docs |
| Relative path | `![diagram](./images/diagram.png)` | Projects with an `images/` folder |
| Obsidian embed | `![[photo.jpg]]` | Notes inside an Obsidian vault |

---

## Code and Code Blocks

### Inline code

Wrap short code in single backticks:

```markdown
Use the `git status` command to see what changed.
```

Renders as: Use the `git status` command to see what changed.

### Fenced code blocks

For multi-line code, use triple backticks on their own lines:

````markdown
```bash
git clone https://github.com/user/repo.git
cd repo
git status
```
````

### Syntax highlighting

Add a language name after the opening backticks:

````markdown
```python
def greet(name):
    print(f"Hello, {name}!")
```
````

````markdown
```javascript
const hello = () => console.log("Hello!");
```
````

Common language tags: `bash`, `python`, `javascript`, `json`, `html`, `css`, `markdown`, `text`

### Escaping backticks

If you need to show backticks inside inline code, use double backticks on the outside:

```markdown
``Use `backticks` like this``
```

---

## Blockquotes and Callouts

### Basic blockquotes

Start a line with `>`:

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

Renders as an indented, styled quote block.

### Nested blockquotes

```markdown
> Level one
>> Level two
>>> Level three
```

### Callouts (Obsidian and some other apps)

Obsidian supports callout boxes with this syntax:

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

> [!TIP]
> Helpful advice.

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

These are extensions — they will not render in plain GitHub Markdown, but work great in Obsidian.

---

## Tables

Tables are part of GitHub Flavored Markdown and work in most modern editors.

### Basic table

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

### Alignment

```markdown
| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| aligned  | aligned  | aligned  |
```

- `:---` = left align (default)
- `:---:` = center
- `---:` = right align

### Tips for tables

- Keep them simple — complex tables are hard to edit in plain text
- For very wide data, consider a link to a spreadsheet instead
- Obsidian and GitHub both render tables; some older Markdown viewers do not

---

## Horizontal Rules and Line Breaks

### Horizontal rule (divider line)

Three or more of `-`, `*`, or `_` on their own line:

```markdown
---
***
___
```

All create a horizontal divider between sections.

### Line breaks within a paragraph

**Option 1:** End a line with two spaces, then press Enter (hard to see — not recommended)

**Option 2:** Use a blank line between paragraphs (recommended)

**Option 3:** Use `<br>` HTML tag (works in most renderers):

```markdown
First line<br>
Second line on a new row
```

---

## Task Lists (Checkboxes)

GitHub Flavored Markdown and Obsidian support checkboxes:

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

Renders as interactive checkboxes in GitHub, Obsidian, and many editors.

**Note:** The space inside the brackets matters: `[ ]` not `[]`.

---

## Where You'll Use Markdown

| Tool / Place | What you write | Example |
|---|---|---|
| **GitHub** | README files, docs, issue comments, PR descriptions | `README.md` in every repo |
| **Obsidian** | Every note in your vault | `Meeting Notes.md`, daily journals |
| **Cursor / VS Code** | Docs, comments, AI prompts, project notes | `.md` files in your project |
| **Slack / Discord** | Quick formatting in messages | `*bold*`, `` `code` ``, `> quote` |
| **Static site generators** | Blog posts and pages | Jekyll, Hugo, Eleventy, MkDocs |
| **Notion** | Partial support when exporting/importing | `/markdown` blocks |
| **Reddit / Stack Overflow** | Comments and posts | Limited Markdown subsets |

### The Aspi 101 connection

This guide series is written entirely in Markdown:

- Read the [[github-for-beginners|GitHub guide]] to learn where `.md` files live in repos
- Read the [[obsidian-for-beginners|Obsidian guide]] to learn how Markdown powers linked notes
- You are reading Markdown right now — this file is `markdown-for-beginners.md`

---

## Markdown Flavors (GitHub vs. Obsidian)

Not all Markdown is identical. Here is 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 |
| Syntax highlighting | Sometimes | Yes | Yes |
| Wikilinks `[[note]]` | No | No | Yes |
| Callouts `> [!NOTE]` | No | No | Yes |
| Embeds `![[file]]` | No | No | Yes |
| Frontmatter `---` | No | Sometimes | Yes |

**Rule of thumb:** Stick to standard syntax (headings, bold, lists, links, code blocks) and your files work everywhere. Add Obsidian-specific features only in Obsidian vaults.

---

## Common Mistakes and How to Avoid Them

| Mistake | What happens | Fix |
|---|---|---|
| Forgetting space after `#` | `#Heading` may not render as heading | Always write `# Heading` with a space |
| Missing blank line before list | List merges into paragraph above | Add a blank line before `- item` |
| Unclosed `**` or `` ` `` | Bold/code runs to end of file | Count your opening and closing markers |
| Broken link syntax | `[text](url` missing `)` shows raw text | Check parentheses match: `[text](url)` |
| Pasting formatted Word text | Carries hidden formatting garbage | Paste as plain text, then re-add Markdown |
| Using HTML when MD works | Harder to read and edit | Prefer Markdown syntax over `<b>`, `<h1>`, etc. |
| Huge tables in Markdown | Painful to edit by hand | Link to a spreadsheet for large datasets |
| Wrong code fence count | Code block never closes | Use exactly three backticks to open and close |

### Debugging tip

When formatting looks wrong, switch to **source/raw mode** (in Obsidian: `Cmd+E`; in VS Code/Cursor: open the `.md` file directly). Read the characters literally — the problem is almost always a missing space, backtick, or blank line.

---

## Markdown vs. Other Formats

| Format | What it is | When to use it |
|---|---|---|
| **Markdown (.md)** | Plain text with simple formatting characters | Notes, docs, READMEs, anything in Git/Obsidian |
| **Word (.docx)** | Proprietary rich document format | Formal reports, heavy layout, track changes with non-technical colleagues |
| **Google Docs** | Cloud word processor | Real-time collaboration on prose documents |
| **HTML (.html)** | Web page markup | Published websites, precise layout control |
| **PDF** | Fixed-layout final output | Sharing finished documents that should not be edited |
| **Plain text (.txt)** | Zero formatting | Logs, config files, when formatting does not matter |

**Choose Markdown when:** you want portable, version-controllable, plain-text documents that work in GitHub, Obsidian, and code editors.

**Choose something else when:** you need WYSIWYG layout design, tracked changes in Word, or pixel-perfect print formatting.

---

## Quick Reference Cheat Sheet

```markdown
# Heading 1
## Heading 2
### Heading 3

Regular paragraph. Blank line between paragraphs.

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

- Bullet item
  - Nested bullet
1. Numbered item
2. Second item

- [ ] Task unchecked
- [x] Task done

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

> Blockquote

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

---
Horizontal rule
```

### Fenced code block

````markdown
```bash
echo "Hello, Markdown"
```
````

### Obsidian extras (Obsidian only)

```markdown
[[Note Title]]
[[Note Title|Display text]]
[[Note Title#Heading]]
![[image.png]]
> [!TIP] Helpful tip here
```

---

## 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]]` |
| **Frontmatter** | YAML metadata block at the top of a file between `---` lines |
| **Fenced code block** | Multi-line code surrounded by triple backticks |
| **Inline code** | Short code snippet wrapped in single backticks |
| **Blockquote** | Quoted text starting with `>` |
| **Alt text** | Description of an image for accessibility |
| **Syntax highlighting** | Color-coding code blocks by programming language |
| **Flavor / variant** | An app's specific extensions to standard Markdown |
| **CommonMark** | A standardized specification of core Markdown syntax |

---

*You do not need to memorize every syntax rule. Start with headings, bold, lists, and links — then look up the rest as you need it. The best way to learn Markdown is to write in it.*