Markdown Cheatsheet: The Complete Developer's Writing Guide

Markdown is the de facto writing format for developers. README files, GitHub issues, pull request descriptions, documentation sites, blog posts, wiki pages — if you work with text in a technical context, you're writing Markdown. John Gruber created it in 2004 with one goal: to be readable as plain text while also converting cleanly to HTML. It succeeded spectacularly.

This guide covers every Markdown feature you'll actually use, including GitHub Flavored Markdown (GFM) extensions that aren't in the original spec but are supported everywhere that matters.

Headings

Use hash symbols followed by a space. The number of hashes equals the heading level (h1–h6).

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Alternatively, you can use setext-style headings for h1 and h2 by underlining with = or -, though hash-style is more widely supported and easier to maintain.

Emphasis

**bold text** or __bold text__
*italic text* or _italic text_
***bold and italic*** or ___bold and italic___
~~strikethrough~~ (GFM only)

Lists

Unordered Lists

Use -, *, or + as list markers. Be consistent within a list.

- Item one
- Item two
  - Nested item (two spaces indent)
  - Another nested item
- Item three

Ordered Lists

1. First item
2. Second item
3. Third item
   1. Nested ordered item
   2. Another nested item

A useful trick: you can use 1. for every item and most renderers will auto-number correctly. This makes reordering items easier without renumbering.

Task Lists (GFM)

- [x] Write the article
- [x] Add code examples
- [ ] Add screenshots
- [ ] Publish

Links

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

<!-- Reference-style links (cleaner for long documents) -->
[Link text][ref-id]
[ref-id]: https://example.com "Optional title"

<!-- Autolinks -->
<https://example.com>
<email@example.com>

Images

Same syntax as links, but prefixed with an exclamation mark. The text in brackets becomes the alt attribute.

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

<!-- Reference-style -->
![Alt text][img-ref]
[img-ref]: image.png "Title"

Code

Inline Code

Wrap with single backticks: `code here`

Fenced Code Blocks

Use triple backticks with an optional language identifier for syntax highlighting:

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

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

```bash
npm install && npm run build
```

Language identifiers for common types: javascript, typescript, python, php, css, html, bash, json, yaml, sql, markdown.

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> And multiple paragraphs.
>
> > Nested blockquotes work too.

Horizontal Rules

Use three or more hyphens, asterisks, or underscores on a line by themselves:

---
***
___

Tables (GFM)

Tables use pipe characters to separate columns. The second row defines column alignment:

| Feature       | Basic MD | GFM  |
|---------------|:--------:|:----:|
| Tables        | No       | Yes  |
| Task lists    | No       | Yes  |
| Strikethrough | No       | Yes  |
| Footnotes     | No       | Yes  |

Alignment: :--- left (default), :---: center, ---: right.

Footnotes (GFM)

Here's some text with a footnote.[^1]

[^1]: The footnote content goes here.

Escaping Characters

Use a backslash to render Markdown-special characters literally:

\*This is not italic\*
\# This is not a heading

HTML in Markdown

Most Markdown renderers allow raw HTML inline. This is useful for things Markdown doesn't support, like custom attributes or alignment:

<div style="text-align: center;">
  Centered content
</div>

<details>
  <summary>Click to expand</summary>
  Hidden content here.
</details>

GitHub Flavored Markdown vs Standard Markdown

GFM is the superset supported by GitHub, GitLab, Bitbucket, and most modern platforms. GFM adds:

• Tables
• Task lists (- [x])
• Strikethrough (~~text~~)
• Autolinks (bare URLs become clickable)
• Footnotes
• Emoji shortcodes (:rocket:)
• @mentions and #issue references (platform-specific)

When in doubt, test your Markdown in the environment where it will be displayed. GitHub's renderer differs slightly from VS Code's, which differs from Notion's.