Markdown for Developers: The Complete Reference Guide

Markdown is the lingua franca of developer documentation — README files, GitHub issues, pull requests, Notion, Slack, Discord, and most documentation sites all render it. This is your complete reference.

Basic Syntax

# H1 Heading
## H2 Heading
### H3 Heading

**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~

A paragraph is just text with a blank line above it.

A line break at the end of a line  
requires two spaces before the newline.

> Blockquote text
> can span multiple lines

--- (horizontal rule)

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Hover title")
[Reference link][ref-id]

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

[ref-id]: https://example.com "Reference definition"

<!-- Auto-link -->
<https://example.com>
<user@example.com>

Lists

<!-- Unordered -->
- Item one
- Item two
  - Nested item (indent 2 spaces)
  - Another nested
- Item three

<!-- Ordered -->
1. First
2. Second
   1. Nested ordered
3. Third

<!-- Task list (GitHub Flavored Markdown) -->
- [x] Completed task
- [ ] Pending task
- [ ] Another pending

Code

Inline `code` with backticks

```javascript
// Fenced code block with language for syntax highlighting
const greet = (name) => `Hello, ${name}!`;
```

```diff
- removed line
+ added line
  unchanged line
```

Tables (GFM)

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell     | Cell     | Cell     |
| Cell     | Cell     | Cell     |

<!-- Alignment -->
| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

GitHub Flavored Markdown (GFM) Extensions

GFM adds several extensions on top of standard Markdown:

Autolinks: Bare URLs like https://example.com become clickable.

Strikethrough: ~~text~~ → text

Task lists: - [x] and - [ ] in GitHub issues and PRs.

Mentions: @username links to a GitHub user.

Issue/PR references: #123 links to an issue, org/repo#123 cross-links.

Emoji: :rocket: → 🚀 — full emoji list

Footnotes:

Here is a claim.[^1]

[^1]: This is the footnote text.

Escaping

\*This is not bold\*
\[This is not a link\]

<!-- HTML comments are hidden in rendered output -->

<!-- HTML is also valid in Markdown -->
<kbd>Ctrl</kbd> + <kbd>C</kbd>
<details>
  <summary>Click to expand</summary>
  Hidden content here.
</details>

Writing a Good README

Every project README should have:

# Project Name

> One-line description

## What Is This?
2-3 sentences explaining what the project does and who it's for.

## Quick Start
```bash
npm install my-package

Usage

Code examples showing the most common use case.

API Reference

Table of functions/options with types and descriptions.

Contributing

How to set up dev environment and submit PRs.

License

MIT / Apache / etc.

Use the Markdown Previewer tool to render and preview your markdown in real time without leaving the browser.