Markdown Mastery: The Writer's Guide to Lightweight Formatting

Created by John Gruber in 2004, Markdown was designed to be readable as plain text while converting cleanly to HTML. Today it's used everywhere—GitHub READMEs, documentation sites, note-taking apps, blogs, and more.

Basic Formatting

Headings

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

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

Lists

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Second item
   1. Nested ordered

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Title")

![Alt text](image.jpg)
![Alt text](image.jpg "Image title")

Code

Inline code uses single backticks:

Use `console.log()` for debugging.

Code blocks use triple backticks with optional language:

```javascript
function hello() {
  console.log("Hello!");
}
```

Blockquotes

> This is a quote.
> It can span multiple lines.
>
> > Nested quotes work too.

Tables

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Alignment with colons:

| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

Horizontal Rules

---
***
___

Any of these create a horizontal line.

Extended Syntax (GitHub Flavored Markdown)

Task Lists

- [x] Completed task
- [ ] Incomplete task

Footnotes

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Automatic Links

URLs and emails automatically become clickable in most Markdown parsers.

Best Practices

• Use blank lines between elements for clarity
• Be consistent with emphasis markers (* vs _)
• Use reference-style links for repeated URLs
• Preview your Markdown before publishing
• Keep lines reasonably short for version control

Common Mistakes

• Missing blank lines: Paragraphs need blank lines between them
• Inconsistent indentation: Nested lists need 2-4 spaces
• Forgetting escapes: Use backslash to escape special characters
• Broken links: Always test links before publishing

Why Markdown Wins

Markdown succeeds because it's readable even without rendering. A Markdown file is just text—it works in any editor, survives any platform, and will be readable in 50 years. That's the power of plain text with just enough formatting to be useful.