README.md Markdown Syntax Cheat Sheet

GitHub README files use Markdown for formatting. This cheat sheet covers every syntax element you'll need, from basic text formatting to advanced features like task lists and collapsible sections.

Headings

Use # symbols to create headings. More # means a smaller heading.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Use H1 for the project title, H2 for major sections, and H3 for subsections. Don't skip levels — go from H2 to H3, not H2 to H4.

Text formatting

**Bold text**
*Italic text*
~~Strikethrough~~
**Bold and _italic_ combined**
`Inline code`

Links

[Link text](https://example.com)
[Link with title](https://example.com "Hover title")
[Relative link](docs/guide.md)
[Section link](#installation)

Anchor links use lowercase heading text with hyphens replacing spaces: ## Getting Started becomes #getting-started.

Images

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

For sizing images on GitHub, use HTML:

<img src="screenshot.png" width="600" alt="Screenshot">

Code blocks

Wrap code in triple backticks. Specify the language for syntax highlighting:

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

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

Lists

Unordered lists

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

Ordered lists

1. First step
2. Second step
3. Third step

Task lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Task lists render as checkboxes on GitHub.

Tables

| Feature | Free | Pro |
|---------|------|-----|
| Generations | 3/month | Unlimited |
| Private repos | No | Yes |
| Push to GitHub | No | Yes |

Align columns with colons:

| Left | Center | Right |
|:-----|:------:|------:|
| text | text   | text  |

Blockquotes

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

> **Note**: GitHub also supports alerts:

> [!NOTE]
> Useful information.

> [!WARNING]
> Critical content.

> [!TIP]
> Helpful advice.

Horizontal rules

---

Use horizontal rules to separate major sections visually.

Badges

Badges are image links that show project metadata:

![Build Status](https://img.shields.io/github/actions/workflow/status/owner/repo/ci.yml)
![License](https://img.shields.io/github/license/owner/repo)
![Version](https://img.shields.io/npm/v/package-name)

Visit shields.io to generate badges for your project. Our GitHub README badges guide covers this in depth.

Collapsible sections

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

Hidden content here. Leave a blank line after `<summary>`.

</details>

Useful for long configuration examples, changelogs, or optional details.

HTML in Markdown

GitHub Markdown supports a subset of HTML. Common uses:

<!-- Center an image -->
<p align="center">
  <img src="logo.png" width="200" alt="Logo">
</p>

<!-- Keyboard keys -->
Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy.

<!-- Superscript / subscript -->
H<sub>2</sub>O and E = mc<sup>2</sup>

Emoji

Use emoji shortcodes:

:rocket: :star: :bug: :white_check_mark: :warning:

Renders as: 🚀 ⭐ 🐛 ✅ ⚠️

Footnotes

This has a footnote[^1].

[^1]: Footnote content here.

Putting it all together

A well-structured README combines these elements. Start with a title, badges, and description. Use headings to organize sections. Add code blocks for installation and usage. Include tables for configuration. Use images for visual projects.

Need help structuring your README? Generate one automatically from your codebase, or check out our README template guide for a ready-made starting point.

For projects in specific languages, browse our JavaScript README generator or Python README generator pages.