GitHub Markdown Cheat Sheet for READMEs

GitHub uses GitHub Flavored Markdown, which is standard Markdown plus tables, task lists, alerts and a safe subset of HTML. This cheat sheet covers what you actually need for a README, including the HTML tricks that make profile READMEs look polished.

Headings and text

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

**bold**, *italic*, ~~strikethrough~~, `inline code`

Line one
Line two   ← end a line with two spaces, or use <br>, for a line break

Lists and task lists

- Bullet item
  - Nested item (indent two spaces)
1. Numbered item
2. Another item

- [x] Done
- [ ] To do

Links and images

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

[![Clickable image](https://example.com/badge.svg)](https://example.com)

Relative paths work for files in the same repository: ![Diagram](docs/diagram.png).

Resizing images

Markdown can't size images, so use an HTML tag with a width or height:

<img src="banner.png" alt="Banner" width="100%" />
<img src="avatar.png" alt="Me" width="120" />

Centring content

GitHub removes CSS, so style="text-align:center" does nothing. Use the align attribute instead:

<p align="center">
  <img src="banner.png" alt="Banner" width="100%" />
</p>

<h2 align="center">About me</h2>

<div align="center">

  Markdown **works** in here as long as you leave a blank line after the opening tag.

</div>

align="right" on an image floats it to the right of the following text, which is handy for an avatar beside an intro.

Different images for light and dark mode

Use <picture> with a prefers-color-scheme media query. GitHub shows the matching source for each viewer's theme:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="logo-dark.png" />
  <source media="(prefers-color-scheme: light)" srcset="logo-light.png" />
  <img alt="Project logo" src="logo-light.png" />
</picture>

Alerts (callouts)

GitHub renders these blockquotes as coloured callout boxes:

> [!NOTE]
> Useful information.

> [!TIP]
> Helpful advice.

> [!IMPORTANT]
> Key information.

> [!WARNING]
> Needs attention.

> [!CAUTION]
> Risk of a negative outcome.

Collapsible sections

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

  Hidden content. Leave a blank line after </summary> so Markdown inside renders.

</details>

Code blocks

Fence code with three backticks and add the language for syntax highlighting:

```ts
const greet = (name: string) => `Hello, ${name}!`;
```

```diff
- removed line
+ added line
```

Tables

| Tool    | Use            | Since |
| :------ | :------------: | ----: |
| React   | UI             |  2019 |
| Docker  | Deployments    |  2021 |

Colons in the divider row set alignment: left :---, centre :---:, right ---:.

Emoji, footnotes, maths and more

:rocket: :tada: :wave:            ← emoji shortcodes, or paste emoji directly

Here's a claim.[^1]
[^1]: And its footnote.

Inline maths $E = mc^2$ and a block:
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

<kbd>Ctrl</kbd> + <kbd>C</kbd>      ← keyboard keys

@username mentions a user, #123 links an issue in repository READMEs, and  hides text from the rendered page.

What HTML GitHub allows

GitHub sanitises README HTML for security. In practice:

Works	Removed
`<p>`, `<div>`, `<h1>`–`<h6>` with `align`	`style` attributes and `<style>` tags
`<img>` with `width`, `height`, `align`, `hspace`, `vspace`	`<script>`, `<iframe>`, forms and inputs
`<picture>`, `<details>`, `<summary>`, `<table>`, `<kbd>`, `<br>`	Most event and class attributes

Because CSS is stripped, animation and custom styling in profile READMEs comes from images, usually SVGs generated by services. That's how animated banners and typing text work. See profile README ideas for examples.

Preview before you commit

On GitHub, the Preview tab in the file editor shows the rendered result. For profile READMEs, the MakeReadme generator previews your README inside a mock GitHub profile in both light and dark mode, and on mobile.

💡 Skip the HTML by hand: build your profile README visually and download the Markdown. Try it →