Markdown Cheat Sheet: The Definitive Reference

Why This Cheat Sheet Exists

Markdown has become the universal writing format for developers. README files, documentation sites, issue trackers, pull request descriptions, Slack messages, Notion pages, and blog posts all use some variant of Markdown. Despite its simplicity, the syntax has enough features and edge cases that even experienced developers find themselves searching for the exact syntax for tables, footnotes, or nested lists.

This reference covers the full GitHub Flavored Markdown (GFM) specification, which is the most widely supported variant. GFM extends the original Markdown spec by John Gruber with features like task lists, tables, strikethrough, and auto-linked URLs. Every example below shows the raw syntax alongside what it produces, so you can see both sides at a glance. If you want to experiment interactively, open our Markdown Preview tool in a second tab and paste any syntax to see it rendered in real time.

Headings

Headings create the structural outline of your document. Markdown supports six levels of headings, matching HTML's <h1> through <h6>. In practice, most documents only use three or four levels. The number of # characters before the heading text determines the level.

# Heading 1       (largest, use for page title)
## Heading 2      (section titles)
### Heading 3     (subsections)
#### Heading 4    (sub-subsections)
##### Heading 5   (rare in most documents)
###### Heading 6  (smallest)

Always leave a blank line before and after headings. While some parsers are lenient, omitting the blank line can cause rendering issues. Also ensure there is a space between the # characters and the heading text: # Correct works, but #Incorrect may not render as a heading in all parsers.

Alternative syntax exists for h1 and h2 using underlines. Placing any number of = characters on the line below text creates an h1, and - characters create an h2. This style is less common but sometimes appears in older documents:

Heading 1 (alternative)
=======================

Heading 2 (alternative)
-----------------------

Text Emphasis and Formatting

Markdown provides several ways to emphasize text. The core formatting options are bold, italic, and their combination. GFM adds strikethrough as a commonly used extension.

*italic text*        or  _italic text_
**bold text**        or  __bold text__
***bold italic***    or  ___bold italic___
~~strikethrough~~    (GFM extension)
`inline code`       (monospace, preserves literal characters)

When choosing between asterisks and underscores for emphasis, pick one style and be consistent. Most style guides prefer asterisks because underscores within words can cause ambiguity. For example, some_variable_name should not be interpreted as emphasis, and GFM handles this correctly by only treating underscores as emphasis markers when they are not inside a word.

Inline code is invaluable for mentioning function names, variable names, file paths, command-line arguments, or any literal text that should not be formatted. If you need to include a backtick inside inline code, use double backticks: `` `backtick` `` renders as a backtick surrounded by code formatting.

Links

Links are one of the most frequently used Markdown elements. There are three styles: inline links, reference links, and autolinks.

[Inline link](https://example.com)
[Link with title](https://example.com "Hover title")

[Reference link][ref-id]
[ref-id]: https://example.com "Optional title"

<https://example.com>          (autolink, GFM)
https://example.com            (bare URL, GFM autolinks this too)
<user@example.com>             (email autolink)

Reference-style links are particularly useful in documents with many links. They keep the body text clean and readable by moving URLs to the bottom of the document or section, similar to footnotes in academic writing. The reference ID is case-insensitive, so [ref-id] and [REF-ID] resolve to the same target.

Images

Image syntax is identical to link syntax, with an exclamation mark prepended. The text inside the square brackets becomes the image's alt text, which is essential for accessibility and SEO.

![Alt text](https://example.com/image.png)
![Alt text](image.png "Optional title")

![Reference image][img-ref]
[img-ref]: https://example.com/image.png "Title"

Markdown does not natively support image sizing. To control dimensions, you need to use raw HTML: <img src="image.png" width="300" alt="description" />. Most Markdown renderers, including GitHub, allow inline HTML for situations where pure Markdown syntax falls short.

Lists

Markdown supports both ordered (numbered) and unordered (bulleted) lists. Nesting is achieved through indentation.

Unordered Lists

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

* Asterisks also work
+ Plus signs too (but pick one style and be consistent)

Ordered Lists

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

1. Lazy numbering (all "1." works; the renderer assigns numbers)
1. Second item
1. Third item

The lazy numbering technique (using 1. for every item) is useful because it means you never need to renumber items when inserting or removing list entries. The Markdown renderer will assign sequential numbers automatically.

Task Lists (GFM)

- [x] Completed task
- [x] Another done task
- [ ] Pending task
- [ ] Future work

Task lists are a GFM extension and render as checkboxes on GitHub. They are commonly used in pull request descriptions to track progress and in issue templates to create checklists.

Code Blocks

Fenced code blocks are one of the most important Markdown features for technical writing. They preserve whitespace, disable Markdown parsing inside the block, and support syntax highlighting when a language identifier is provided.

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

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

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

```diff
- old line (removed)
+ new line (added)
```

The language identifier after the opening three backticks enables syntax highlighting. GitHub supports hundreds of languages. Some commonly used identifiers: javascript (or js), typescript (or ts), python, bash (or sh), json, yaml, sql, html, css, go, rust, java, diff, and markdown (or md). Using diff is particularly useful for showing changes, as removed lines (prefixed with -) are typically highlighted in red and added lines (prefixed with +) in green. You can test any of these in our Markdown editor to see how they render.

Indented code blocks (4 spaces or 1 tab) are the original Markdown syntax for code, but fenced blocks with backticks are preferred in modern usage because they support language specification and are easier to read in source form.

One especially powerful use of fenced code blocks is embedding diagrams using the mermaid language identifier. Platforms like GitHub render ```mermaid blocks as flowcharts, sequence diagrams, ER diagrams, and more. You can write and preview Mermaid diagrams with our Mermaid Diagram Renderer.

Blockquotes

Blockquotes are used for citations, callouts, and highlighting important information. They are created with the > character at the start of each line.

> This is a blockquote.
> It can span multiple lines.
>
> Separate paragraphs within a blockquote with a blank quoted line.

> Blockquotes can be nested:
>> Nested blockquote
>>> Deeply nested

> **Note:** You can use other Markdown inside blockquotes,
> including *emphasis*, `code`, and [links](https://example.com).

GitHub has introduced additional blockquote variants for documentation through admonition syntax: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], and > [!CAUTION]. These render with colored icons and backgrounds to draw attention to different types of information.

Tables

Tables are a GFM extension and one of the most commonly looked-up Markdown features. The syntax uses pipes and hyphens to create a visual grid. For a thorough treatment of table formatting, alignment, and advanced techniques, see our dedicated Markdown Table Syntax guide.

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

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Left         |    Center      |         Right |
| Data         |    Data        |          Data |

The colons in the separator row control column alignment. A colon on the left means left-aligned (the default), colons on both sides means centered, and a colon on the right means right-aligned. The pipes at the beginning and end of each row are optional but recommended for readability. If you find table syntax tedious to type manually, use our Markdown tool's Table Generator tab to build tables visually and copy the generated syntax.

Horizontal Rules

Horizontal rules create a visible divider between sections. Three or more hyphens, asterisks, or underscores on a line by themselves create a rule.

---
***
___

(All three produce identical horizontal rules)

Footnotes (GFM Extension)

Footnotes let you add supplementary information without cluttering the main text. They are created with a caret and identifier in square brackets, and the footnote content is defined anywhere in the document.

Here is a sentence with a footnote.[^1]

And another with a named footnote.[^note]

[^1]: This is the footnote content.
[^note]: Named footnotes can be more descriptive.
    Multi-line footnotes work by indenting continuation lines.

Footnotes are rendered at the bottom of the page with automatic back-links. They are especially useful in technical documentation for providing citations, clarifications, or links to external resources without breaking the flow of the main text.

Escaping Special Characters

If you need to display a character that Markdown would normally interpret as formatting, precede it with a backslash.

\*Not italic\*
\# Not a heading
\[Not a link\](not a url)
\`Not inline code\`
\| Not a table pipe
\- Not a list item

Characters that can be escaped: \ ` * _ { } [ ] ( ) # + - . ! |

HTML in Markdown

Markdown allows inline HTML for situations where Markdown syntax is insufficient. This is useful for features like image sizing, definition lists, colored text, or complex layouts. Most Markdown renderers, including GitHub, support a safe subset of HTML tags.

<details>
<summary>Click to expand</summary>

Hidden content here. This is useful for long output,
configuration examples, or supplementary information
that most readers can skip.

</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd>  (keyboard key styling)

<sup>superscript</sup> and <sub>subscript</sub>

<img src="image.png" width="400" alt="Sized image" />

The <details>/<summary> pattern is particularly valuable on GitHub. It lets you include long logs, configuration files, or verbose output in issues and pull requests without overwhelming readers. The content is collapsed by default and only shown when the user clicks the summary.

Line Breaks and Paragraphs

Markdown handles whitespace in ways that sometimes surprise newcomers. Two important rules to remember:

A single newline
does NOT create a new line in the output.
These three lines render as one continuous paragraph.

A blank line between text creates separate paragraphs.

To force a line break without a new paragraph,
end a line with two spaces
or use a backslash at the end\
Both create a <br> in the output.

Advanced: Combining Features

The real power of Markdown comes from combining features. Here are some practical patterns used in real-world documentation:

> **Warning:** Make sure to back up your database before running
> migrations. See the [backup guide](https://example.com/backup)
> for instructions.
>
> ```bash
> pg_dump mydb > backup.sql
> ```

| Feature     | Syntax                    | Support |
|-------------|---------------------------|---------|
| **Bold**    | `**text**`                | All     |
| *Italic*    | `*text*`                  | All     |
| ~~Strike~~  | `~~text~~`                | GFM     |
| Task lists  | `- [x] done`              | GFM     |
| Footnotes   | `text[^1]`                | GFM     |

Markdown is designed to be readable as plain text even before rendering. The best Markdown documents are clean, consistent, and structured in a way that communicates intent clearly in both source and rendered form. For a professional example combining all these features, see our GitHub README Template Generator.