GitHub Markdown and README Formatting

README Files vs Issue Comments

GitHub renders Markdown in two places with slightly different rules: repository files (README.md and every other .md file) and conversations (issues, pull requests, discussions, and their comments). Most “it worked in my issue but not my README” problems come from this table.

This example
Will span two lines

This example
Will span two lines

To force a break in a file, end the line with a backslash, two spaces, or <br> (see line breaks). Our Markdown editor can preview either mode. Wikis have their own gaps: footnotes and autolinked references are not supported there.

Text Styling

Bold, italic, and strikethrough use standard syntax; GitHub accepts one or two tildes for strikethrough. There is no Markdown for underline, subscript, or superscript, so GitHub documents the HTML tags <ins>, <sub>, and <sup>. The older <u> tag is stripped (see underline).

**Bold** or __bold__
*Italic* or _italic_
***Bold and italic***
~~Strikethrough~~ or ~one tilde~
H<sub>2</sub>O and x<sup>2</sup>
<ins>Underlined</ins>
`inline code`

Keyboard shortcuts in GitHub's editor

These work in comment boxes and the file editor on github.com.

Alerts (Callouts)

Alerts are blockquotes whose first line is [!TYPE]. GitHub has five types and draws each with its own color and icon. The type must sit alone on the first line, is case-insensitive, and the alert cannot be nested inside a list or another quote. GitHub's own advice is one or two per document, never back to back.

> [!NOTE]
> Useful information that users should know, even when skimming content.

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

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

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

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

Obsidian reads the same > [!NOTE] syntax as a callout and adds many more types (see Obsidian Markdown); GitHub only recognizes these five.

Tables

Pipes separate columns and a row of hyphens separates the header. Colons in that row set alignment: :--- left, :---: center, ---: right. Cells can hold inline formatting, links, and code; a literal pipe inside a cell needs a backslash (\|). The outer pipes are optional and the columns do not have to line up.

| Command | Description | Exit code |
| :--- | :---: | ---: |
| `git status` | List *changed* files | 0 |
| `git diff` | Show **unstaged** changes | 0 |
| a \| b | Escaped pipe | 1 |

More on merged-cell workarounds and line breaks in cells in the table guide, or build one with the table generator.

Task Lists

Start a list item with [ ] for an open task or [x] for a done one. Bulleted and numbered lists both work. In issues, pull requests, and comments the checkboxes are clickable and GitHub rewrites the Markdown for you; in a .md file they are read-only. In conversations, a task item that references an issue or PR shows that issue's title and state.

- [x] Write the parser
- [x] Add tests
- [ ] Update the README
- [ ] Tag a release

GitHub retired the separate tasklist blocks beta in 2025 in favor of sub-issues. Ordinary Markdown task lists like the one above are unaffected. Nesting and per-platform behavior are covered in the checkbox guide.

Code Blocks and Diagrams

Fence code with three backticks and add a language identifier for syntax highlighting. GitHub uses Linguist to pick the grammar, so any name or alias in its languages list works (js, python, diff, bash). To show triple backticks inside a block, fence it with four.

```js
const answer = 42
console.log(answer)
```

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

Four language identifiers turn a code block into a rendered diagram, in files, issues, pull requests, discussions, and wikis:

Not sure GitHub supports a newer Mermaid feature? A mermaid block containing only info prints the version GitHub is running. Full fencing rules are in the code block guide.

Math (LaTeX)

GitHub renders LaTeX math with MathJax in files, issues, pull requests, discussions, and wikis. There are two inline forms and two block forms:

Pythagoras: $a^2 + b^2 = c^2$

Use $`\sqrt{3x-1}+(1+x)^2`$ when the expression has * or _

$$
\sum_{k=1}^n k = \frac{n(n+1)}{2}
$$

```math
\sum_{k=1}^n k = \frac{n(n+1)}{2}
```

A literal dollar sign on the same line as math needs escaping: \$ inside an expression, or <span>$</span> outside one.

$\color{orange}{\text{This is orange text}}$

Because GitHub strips CSS, people color text with MathJax's \color command. It is not a GitHub-documented feature, it renders in a math font, and links inside it do not work. Other options are in the text color guide.

Autolinks, Mentions, Emoji, and Color Swatches

GitHub turns some plain text into links or widgets. Watch the last column: issue, PR, and commit references are not linked in README or other repository files, or in wikis.

“Conversations” means issues, pull requests, discussions, and their comments. A mention notifies someone only if they have read access to the repository (and, for an organization's repository, are a member of the organization). Color models (#RRGGBB, rgb(R,G,B), hsl(H,S,L)) need backticks and no spaces inside them. For emoji, type : in a comment box to search, or see the full shortcode list.

Section Links and Relative Links

Every heading gets an anchor. GitHub builds it by lowercasing the text, turning spaces into hyphens, dropping other punctuation and Markdown formatting, and adding -1, -2 to repeats. Rendered files with two or more headings also get an automatic table of contents under the Outline button.

## Getting Started
## FAQ & Troubleshooting

[Jump to setup](#getting-started)
[Read the FAQ](#faq--troubleshooting)
[Contributing guide](docs/CONTRIBUTING.md)
[Repo-root path](/LICENSE)

<a name="config"></a>
[Jump to config](#config)

Prefer relative links for files in your own repo: GitHub rewrites them for whatever branch the reader is on, and they keep working in clones. Keep the link text on one line. More on IDs in the headings guide and on link syntax in the links guide.

Images: Size, Center, and Dark Mode

![alt](path) works everywhere, but Markdown has no size or alignment option. On GitHub you switch to an <img> tag, which keeps width, height, and align. For images in your repo, use a relative path such as docs/screenshot.png.

<img src="docs/screenshot.png" width="400" alt="Dashboard screenshot">

<p align="center">
  <img src="docs/logo.png" width="150" alt="App logo">
</p>
<h3 align="center">Centered Title</h3>

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

To make an image clickable, wrap the image in a link. More patterns in the images guide and the centering guide.

What HTML GitHub Allows

GitHub runs your HTML through a sanitizer before rendering it. A small set of tags and attributes survives; anything that could restyle the page is removed. Checked against GitHub's Markdown rendering API.

HTML comments (<!-- -->) are hidden from the rendered page but stay readable in the raw file. See Markdown comments.

Collapsible Sections

<details> and <summary> fold long logs, options, or screenshots behind a click. Leave a blank line after </summary>, or the Markdown inside prints as raw text. Add open to start it expanded.

<details>
<summary>System details</summary>

### Environment
- macOS 15
- Node 22.11.0
</details>

Nesting, headings in the summary, and the indentation trap are in the collapsible sections guide.

Footnotes

Put [^label] where the reference goes and define it anywhere on its own line. GitHub numbers them in order and always renders the notes at the bottom, with a link back. Footnotes work in files and conversations but not in wikis.

GFM is defined by a formal spec.[^1]

[^1]: Published at github.github.com/gfm.

Multi-paragraph notes and other platforms: footnotes guide.

README Template

GitHub's own guidance is that a README should say what the project does, why it is useful, how to get started, where to get help, and who maintains it. This template covers that with the features above. Replace OWNER/REPO and the file paths.

<div align="center">
  <img src="docs/logo.png" width="120" alt="Project logo">

  # Project Name

  One sentence on what this does and who it is for.

  [![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
</div>

## Why

The problem this solves, in two or three sentences.

## Installation

```bash
npm install project-name
```

## Usage

```js
import { thing } from "project-name"

thing({ verbose: true })
```

> [!NOTE]
> Requires Node.js 20 or later.

## Contributing

Pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE)

• GitHub shows the README from .github/, the repository root, or docs/, in that order of preference when there is more than one.
• Anything past 500 KiB is cut off when the README is viewed on GitHub.
• A public repository named exactly like your username turns its README into your profile README, shown at the top of your profile page.
• The blank lines inside the centered <div> are what let the heading and badges render as Markdown.

Common Mistakes

The formatting problems that come up most in READMEs and issue threads.

See #42 for the background.

See [#42](https://github.com/OWNER/REPO/issues/42) for the background.

Line one
Line two

Line one\
Line two

<span style="color:red">Deprecated</span>

> [!WARNING]
> Deprecated: use v2 instead.

> [!NOTE] Read this first.

> [!NOTE]
> Read this first.

<u>underlined</u>

<ins>underlined</ins>

<details>
<summary>Logs</summary>
**Bold** and `code`
</details>

<details>
<summary>Logs</summary>

**Bold** and `code`
</details>

![Logo](logo.png){width=200}

<img src="logo.png" width="200" alt="Logo">

Quick Reference

Every GitHub Markdown feature on this page at a glance.

Frequently Asked Questions