Why Markdown?

Markdown is the universal writing format for developers. README files, documentation sites, blog posts, pull request descriptions, Slack messages — all Markdown. Once you know it, you'll use it every day.

Basic Formatting

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

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

> Blockquote

--- (horizontal rule)

Links and Images

[Link text](https://example.com)
![Alt text](image.jpg)

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


[Google][1]
[1]: https://google.com

Lists

- Item one
- Item two
  - Nested item
  - Another nested


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


- [x] Done task
- [ ] Incomplete task

Code Blocks

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


Use `npm install` to add packages.

Tables (GFM)

| Name    | Role      | Status |
|---------|-----------|--------|
| Alice   | Admin     | Active |
| Bob     | Editor    | Active |
| Charlie | Viewer    | Inactive|

GFM Extensions

GitHub Flavored Markdown adds:

• Task lists: - [ ] todo
• Tables: pipe-separated columns
• Strikethrough: ~~deleted~~
• Autolinks: URLs become clickable automatically
• Code fencing: with syntax highlighting

Extended Syntax Examples

Definition Lists

Term 1
: Definition 1

Term 2
: Definition 2
: Another definition

Footnotes

Here is a footnote reference[^1].

[^1]: Here is the footnote.

Emoji Shortcodes

:smile: :rocket: :point_right: :white_check_mark:

Most platforms support emoji shortcodes — check your platform's supported emoji list.

Real-World Examples

Project README

# Project Name

[![Build Status](https://img.shields.io/badge/build-passing-green)](https://example.com)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

A brief description of what this project does.

## Features

- Feature one
- Feature two
- Feature three

## Installation

```bash
npm install project-name
```

## Usage

```javascript
const project = require('project-name');
project.init();
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing`)
5. Open a Pull Request

API Documentation

## GET /api/users

Returns a list of all users.

### Query Parameters

| Parameter | Type   | Required | Description          |
|-----------|--------|----------|----------------------|
| page      | number | No       | Page number (default: 1) |
| limit     | number | No       | Items per page (default: 20) |

### Response

```json
{
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ],
  "meta": {
    "page": 1,
    "total": 100
  }
}
```

### Status Codes

- `200 OK` — Success
- `401 Unauthorized` — Missing or invalid token
- `500 Server Error` — Internal error

Markdown Editor Tips

• Live preview — Use our Markdown Previewer to see rendered output as you type
• Split view — Many editors (VS Code, Typora) offer side-by-side editing
• Table generators — Use online tools to create tables without manual alignment
• Keyboard shortcuts — Most editors support shortcuts like Ctrl+B for bold

Common Mistakes to Avoid

• Mixed indentation — Use consistent spaces (2 or 4) throughout
• Forgetting blank lines — Block elements need blank lines before and after
• Unescaped special characters — Use backslash to escape: \*
• Overusing HTML — Pure Markdown is more portable
• Broken links — Always verify relative links work from the rendered location

Platform-Specific Notes

| Platform | Special Features ||----------|-----------------|| GitHub | GFM, task lists, autolinks, code highlighting || VS Code | Preview panel, multiple themes || Notion | Callouts, toggles, databases || Reddit | Limited GFM, no tables || Discord | Basic formatting, no code blocks with highlighting |

Frequently Asked Questions

What is the difference between Markdown flavors?

Common flavors: CommonMark (the strict standard), GitHub-Flavored Markdown (GFM — adds tables, task lists, autolinks), MultiMarkdown (footnotes, citations), and Pandoc Markdown (everything plus LaTeX math). Most platforms target GFM. When in doubt, stick to the core CommonMark syntax — it works everywhere.

How do I escape special Markdown characters?

Backslash escapes most chars: \*literal asterisk\* renders as *literal asterisk*. For code spans and code blocks, content is rendered literally — no escaping needed. If your text has a lot of underscores or asterisks, use code formatting to avoid unintended emphasis. For literal hashtags in some renderers, prefix with \.

Can I use HTML inside Markdown?

Yes, all Markdown flavors allow inline HTML for things Markdown can't express:

, , , , complex tables, embedded videos. Use it sparingly — pure Markdown is more portable, easier to convert to other formats, and easier to read as source. The 'Markdown for structure, HTML for edge cases' rule of thumb works well.