Markdown Cheat Sheet: Every Syntax You Need

Markdown is the plain-text formatting language used everywhere — GitHub READMEs, Notion pages, Obsidian vaults, blog posts, Discord messages, and Slack. This reference covers every element you'll need, with copy-ready examples.

Quick reference

The 20 patterns that cover 95% of daily Markdown use.

Headings

Use # symbols for headings. One # = largest, six ###### = smallest. Always leave a space after the #.

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

Alt syntax — underline style (only for H1 and H2):

Heading 1
=========

Heading 2
---------

Use underline syntax sparingly — it's harder to maintain and less universal.

Text emphasis

**bold** or __bold__
*italic* or _italic_
***bold and italic*** or ___bold and italic___
~~strikethrough~~
`inline code`
==highlighted== (Obsidian, Marked, not standard CommonMark)

Rendered output:

• bold
• italic
• bold and italic
• strikethrough
• inline code

Rule: Prefer ** over __ for bold, and * over _ for italic. Underscores behave differently mid-word in many parsers (foo_bar_baz is not italic in CommonMark).

Paragraphs and line breaks

This is paragraph one.

This is paragraph two. A blank line separates paragraphs.

Two spaces at end of line  
forces a line break (trailing spaces).

Or use a backslash\
for a line break (CommonMark).

A single newline without a blank line or trailing spaces creates a soft wrap — it becomes a space in the rendered output, not a new line.

Lists

Unordered list

- Apples
- Bananas
- Cherries
  - Sub-item (indent 2 spaces)
  - Another sub-item
    - Third level

You can also use * or + as list markers — they all work, but pick one and be consistent.

Ordered list

1. First item
2. Second item
3. Third item
   1. Sub-item
   2. Another sub-item

Tip: You can number every item 1. and most parsers will auto-number. Useful when you're inserting items and don't want to renumber the whole list.

1. First item
1. Second item
1. Third item

Task list (GitHub Flavored Markdown)

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

Renders as interactive checkboxes on GitHub, Notion, and Obsidian.

Links

Inline links

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

Reference links

This is [an example][ref] reference link.

[ref]: https://example.com "Optional title"

Reference links keep the body text clean. The reference definitions can go anywhere in the document (usually at the bottom).

Auto-links

<https://example.com>
<user@example.com>

In GitHub Flavored Markdown, bare URLs like https://example.com are auto-linked without angle brackets.

Anchor links (same-page navigation)

[Go to headings section](#headings)

GitHub auto-generates anchors for all headings. The anchor is the heading text lowercased, spaces replaced with -, punctuation removed.

## My Heading! → #my-heading

Images

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

Images use the same syntax as links, with a ! prefix. The alt text is important for accessibility and SEO.

Clickable image (link wrapping an image)

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

Image with reference syntax

![Logo][logo]

[logo]: https://example.com/logo.png "Company Logo"

Blockquotes

> This is a blockquote.
> It can span multiple lines.

> Nested:
> > Inner quote
> > > Deeper nested quote

Blockquotes can contain other Markdown elements:

> ### Heading inside a quote
>
> - A list inside a quote
>
> **Bold** and *italic* work too.

Code

Inline code

Use `backticks` for inline code.

Fenced code block

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

```javascript
const greet = (name) => `Hello, ${name}!`;
console.log(greet("world"));
```

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

```bash
#!/bin/bash
echo "Hello, world!"
```

Common language identifiers:

Indented code block (legacy)

Four spaces or one tab before each line:

    This is a code block.
    Every line is indented 4 spaces.

Avoid this style — fenced code blocks are cleaner and support syntax highlighting.

Horizontal rules

Three or more hyphens, asterisks, or underscores:

---
***
___

All three render as a horizontal line. Use --- for consistency (note: --- immediately after a line creates an H2 heading — leave a blank line above).

Tables (GitHub Flavored Markdown)

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data     | More     |
| Row 2    | Data     | More     |

Column alignment

| Left     | Center   | Right    |
|:---------|:--------:|----------:|
| left     | center   | right    |

• :--- = left-align (default)
• :---: = center-align
• ---: = right-align

Tips:

• You don't need to align the pipe characters — it's just convention for readability.
• Minimum one cell per column, minimum three dashes in the separator row.
• Cells can contain inline Markdown (bold, italic, code, links) but not block elements.

Footnotes (GitHub Flavored Markdown)

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

Another sentence with a named footnote.[^note]

[^1]: This is the footnote text.
[^note]: This is the named footnote text.

Footnotes are rendered at the bottom of the document. Supported on GitHub, Pandoc, and many static site generators — not in all parsers.

Escaping special characters

Backslash escapes any Markdown special character:

\*not italic\*
\# not a heading
\[not a link\](really)
\`not code\`

Special characters that need escaping: \ \* _ { } [ ] ( ) # + - . !

HTML in Markdown

Raw HTML works in most Markdown parsers:

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

Content inside the details element.

</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd>

Renders as keyboard key badges: Ctrl + C

<mark>Highlighted text</mark>

Warning: GitHub sanitizes HTML in Markdown. Some tags and attributes are stripped for security. Avoid inline style="" attributes — they're usually removed.

Practical patterns

README structure

# Project Name

Short description of what this does.

## Installation

```bash
npm install my-package

Usage

const pkg = require('my-package');
pkg.doSomething();

API

License

MIT

### Alert boxes (GitHub Markdown, 2023+)

```markdown
> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Only supported on GitHub (not in standard CommonMark).

Definition list (Pandoc, kramdown)

Term
:   Definition of the term.

Another term
:   Another definition.

Not supported in CommonMark or GFM, but works with Pandoc and Jekyll's kramdown.

Math (Pandoc, some static site generators)

Inline math: $E = mc^2$

Block math:
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Flavors and compatibility

GFM (GitHub Flavored Markdown) is the most widely used extension of CommonMark. When in doubt, stick to CommonMark + GFM table/task list syntax for maximum portability.

6 common mistakes

1. No blank line before a list

Some text
- List item   ← may not render as a list in all parsers

Some text

- List item   ← correct

2. Spaces inside code backticks

` code `    ← some parsers render the spaces literally
`code`      ← correct

3. Forgetting to escape pipes in table cells

| Command | Description |
|---------|-------------|
| `a | b` | Pipe in command |   ← breaks the table
| `a \| b` | Pipe in command |  ← correct

4. Indenting fenced code blocks

  ```javascript     ← indented code block — breaks in some parsers
  const x = 1;
  ```

Keep fenced code blocks at the root indentation level (no leading spaces).

5. Using _ for bold in mid-word contexts

foo_bar_baz     ← not italic in CommonMark
foo*bar*baz     ← italic in some parsers (avoid)

Use ** and * for all emphasis to avoid inter-word parsing edge cases.

6. Heading without blank line above

Paragraph text.
## Heading    ← works, but some parsers require a blank line above

Paragraph text.

## Heading    ← always safe

6 FAQ

Q: What's the difference between Markdown and MDX?

MDX is Markdown with JSX support — you can import and use React components inside your .mdx files. Used in Next.js docs, Astro, Docusaurus. Standard Markdown parsers can't parse MDX.

Q: GitHub Markdown vs standard Markdown — what's different?

GitHub uses GFM (GitHub Flavored Markdown), which adds tables, task lists, strikethrough, footnotes, and auto-linking URLs. GFM is a strict superset of CommonMark, so all standard Markdown works on GitHub.

Q: How do I add a table of contents?

Manually with anchor links:

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [API](#api)

GitHub renders a built-in TOC menu for READMEs automatically. Many static site generators (Astro, Hugo, Jekyll) generate TOC automatically from headings.

Q: Can I use Markdown in HTML files?

Not natively — browsers don't parse Markdown. You need a parser like marked.js or markdown-it to convert Markdown to HTML on the client or server side.

Q: How do I add line breaks inside a table cell?

Use an HTML <br> tag:

| Column |
|--------|
| Line 1<br>Line 2 |

Q: What's the best Markdown editor?

• Writing/notes: Obsidian (local-first, plugin ecosystem), Typora (WYSIWYG)
• Code documentation: VS Code with Markdown Preview
• Online: HackMD, StackEdit, Dillinger
• GitHub: built-in editor with live preview