PureTools

Markdown Syntax: The Complete Cheatsheet

PureTools Team· 7 min read
Markdown Syntax: The Complete Cheatsheet

Markdown: Write Once, Render Everywhere

Markdown is the lingua franca of developer documentation. README files, pull request descriptions, Notion pages, Slack messages, and static site generators all use it. Learn the syntax once and you can write formatted content anywhere.

Basic Text Formatting

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

> Blockquote — great for highlighting important notes
>
> Multi-line blockquotes work too

Renders as: bold text, italic text, bold and italic, strikethrough, inline code.

Headings

# Heading 1    (page title — use once)
## Heading 2   (major sections)
### Heading 3  (subsections)
#### Heading 4 (rarely needed)

Alternate syntax:
Heading 1
=========

Heading 2
---------

Links and Images

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

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


[Google][1]
[GitHub][gh]

[1]: https://google.com
[gh]: https://github.com

Lists

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

Ordered:
1. First
2. Second
3. Third
   1. Nested ordered

Task list (GitHub):
- [x] Completed task
- [ ] Pending task
- [ ] Another pending

Code Blocks

Inline: Use `const x = 1` in your code.

Fenced block with syntax highlighting:
```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

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

```bash
curl -X POST https://api.example.com/data \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'
```

Tables

| Feature    | Markdown | HTML    |
|------------|----------|---------|
| Learning   | Easy     | Medium  |
| Readability| High     | Low     |
| Flexibility| Medium   | High    |

Alignment:
| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

Horizontal Rules

Three or more dashes, asterisks, or underscores:

---
***
___

GitHub-Flavored Markdown (GFM)

GitHub adds several extensions:

Autolinked URLs: https://github.com

Mention users: @username
Reference issues: #123
Reference commits: abc1234

Emoji: :rocket: :tada: :bug:

Footnotes:
This has a footnote[^1].

[^1]: This is the footnote content.

Alerts (since 2023):
> [!NOTE]
> Useful information.

> [!WARNING]
> Critical content.

> [!TIP]
> Helpful advice.

Escaping Special Characters

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

Best Practices for READMEs

  • Start with a clear title and one-line description of what the project does
  • Add badges (build status, npm version, license) right after the title
  • Include a Quick Start section with copy-pasteable install + run commands
  • Use headings to create a scannable structure: Installation, Usage, API, Contributing
  • Add code examples with the language specified for syntax highlighting

Convert your Markdown: Markdown to HTML — paste Markdown, get clean HTML instantly.

← Back to blog