Markdown Syntax Cheat Sheet: Every Feature You Need to Know

Markdown is a lightweight markup language used in GitHub READMEs, docs sites, blogs, Slack messages, and more. This cheat sheet covers every syntax element you'll need — from basic formatting to tables, task lists, and extended features.

Headings

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

Always put a space after the #. Most style guides recommend using only one # Heading 1 per document (the title), then ## for sections.

Text Formatting

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

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

Links and Images

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

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

<!-- Reference-style links (useful for repeated URLs) -->
[DevBolt][1] is a collection of [free tools][1].

[1]: https://devbolt.dev

Reference-style links keep your Markdown readable when the same URL appears multiple times.

Lists

<!-- Unordered lists (use -, *, or +) -->
- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

<!-- Ordered lists -->
1. First item
2. Second item
3. Third item

<!-- The numbers don't matter — Markdown auto-numbers -->
1. First
1. Second
1. Third

Task Lists

Supported by GitHub, GitLab, and most Markdown renderers:

- [x] Write the README
- [x] Add installation instructions
- [ ] Write contributing guidelines
- [ ] Add changelog

Code Blocks

Use triple backticks with a language identifier for syntax highlighting:

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

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

```bash
npm install && npm run dev
```

Common language identifiers: javascript, typescript, python, go, rust, bash, sql, json, yaml, css, html, diff.

Tables

| Feature    | Free  | Pro   |
| ---------- | ----- | ----- |
| Tools      | All   | All   |
| API Access | No    | Yes   |
| Support    | Forum | Email |

<!-- Column alignment -->
| Left   | Center  | Right  |
| :----- | :-----: | -----: |
| text   |  text   |   text |

Table alignment uses colons: :--- for left, :---: for center, ---: for right. Building tables by hand is tedious — use our Markdown Table Generator to create them visually.

Horizontal Rules

---
***
___

(Three or more hyphens, asterisks, or underscores)

Escaping Characters

Prefix special characters with a backslash to display them literally:

\* Not italic \*
\# Not a heading
\[Not a link\](not-a-url)
\`Not code\`

Special characters you can escape:
\  `  *  _  {}  []  ()  #  +  -  .  !  |

GitHub-Flavored Markdown (GFM)

GitHub extends standard Markdown with several features:

Autolinks

<!-- URLs and emails are automatically linked -->
https://devbolt.dev
user@example.com

<!-- Issue and PR references -->
#123
org/repo#456

Alerts / Callouts

> [!NOTE]
> Useful background information.

> [!TIP]
> Helpful advice for better results.

> [!IMPORTANT]
> Key information users should know.

> [!WARNING]
> Potential issues to be aware of.

> [!CAUTION]
> Risks of certain actions.

Footnotes

Here is a statement that needs a citation.[^1]

And another one with a named footnote.[^note]

[^1]: This is the footnote content.
[^note]: Named footnotes work too.

Collapsed Sections

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

Hidden content goes here.
You can use **Markdown** inside.

```js
console.log("Even code blocks work!");
```

</details>

Mermaid Diagrams

```mermaid
graph LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Do thing]
  B -->|No| D[Skip]
  C --> E[End]
  D --> E
```

README Best Practices

A good README should include these sections:

1. 1Title and description — what the project does in one sentence.
2. 2Installation — how to get it running locally.
3. 3Usage — a quick example or screenshot.
4. 4API / Configuration — if applicable.
5. 5Contributing — how others can help.
6. 6License — always include one.

Our README Generator can scaffold a complete README with all these sections in seconds.

Common Mistakes

• Missing blank lines. Headings, code blocks, lists, and blockquotes need a blank line before them. Without it, many parsers won't render them correctly.
• Broken reference links. If you use [text][ref] but forget the [ref]: url definition at the bottom, the link won't render.
• Inconsistent list markers. Mixing -, *, and + in the same list is valid but looks messy. Pick one and stick with it.
• Forgetting image alt text. ![](image.png) works but is bad for accessibility. Always describe the image: ![Screenshot of dashboard](image.png).
• No language on code fences. Always specify the language after the backticks (```js) for proper syntax highlighting.

Try It Yourself

Use our Markdown Preview to write and preview Markdown in real time. Need to create a table? The Markdown Table Generator builds them visually. And if you're converting between HTML and Markdown, try the HTML ↔ Markdown Converter.