How to Use Markdown in a GitHub README: Syntax, Tables & TOC

GitHub READMEs render Markdown automatically. A clear README raises trust, helps people install your project, and makes contributions less confusing. Below are the pieces that show up in almost every strong repo—copy the patterns and adjust the words.

The default file name is README.md at the repository root; GitHub displays it under the file list on the repo home page. You can add more .md files (for example CONTRIBUTING.md) and link to them from the README. Whatever you ship, prefer short sections and scannable lists—most visitors decide whether to stay in under a minute.

Screenshots and GIFs use the same image syntax; store assets in docs/ or .github/ and reference them with relative paths so forks and local clones render the same way as GitHub.com.

The essentials (headings, bold, lists, code)

**Headings** use # through ###### for six levels. GitHub styles them with predictable hierarchy—one H1 per README is enough.

markdown

# Project name
## Install
### Requirements

Bold and italic wrap text in double or single asterisks (or underscores).

markdown

**Bold label:** description.
*Italic note:* optional emphasis.

**Lists:** use - or * for bullets; use 1. for ordered steps.

markdown

- Clone the repo
- Run `npm install`

1. Create `.env`
2. Start the dev server

Inline code uses single backticks; fenced code blocks use triple backticks with an optional language tag for highlighting.

markdown

Use `npm run build` for production.

TypeScript example with syntax highlighting:

export function greet(name: string) {
  return `Hello, ${name}`;
}

**Links:** [visible text](https://example.com). Images are the same with a leading !.

Together, these six patterns cover most READMEs: structure (headings), emphasis, procedures (lists), and copy-pasteable commands (code).

**Blockquotes** use a > prefix and are useful for deprecation notices or quoting policy:

markdown

> **Note:** Requires Node 20 or newer.

Horizontal rules (--- on a blank line) separate major sections when you do not want another heading level.

**Strikethrough** uses double tildes (~~deprecated~~) when you want retired options called out without deleting history.

Tables in GitHub Markdown

GitHub Flavored Markdown (GFM) supports pipe tables: a header row, a separator row with dashes, then body rows.

markdown

| Command        | Purpose        |
| -------------- | -------------- |
| `npm test`   | Run unit tests |
| `npm run dev`| Local server   |

Alignment hints go in the separator row (:---, :---:, ---: for left, center, right). If you prefer not to hand-align pipes, use the free Markdown Table Generator: edit cells visually, set column alignment, then paste the generated table into your README.

Avoid wide tables with long unbroken text—on mobile they force horizontal scrolling. Trim cell copy or split a monster table into two smaller ones with clearer headings.

Badges and shields

Relative links inside the repo ([docs](./docs/architecture.md)) work everywhere GitHub renders Markdown; absolute links to github.com are fine but couple your README to a single host.

**Shields.io** (and similar) generates small SVG badges—build status, license, version, coverage—that you embed as images in Markdown. A typical line looks like ![build](https://img.shields.io/...) linking to your CI or package registry. Keep badges to a handful so the top of the README stays scannable.

Linking to sections within the README

GitHub auto-generates anchors from headings: lowercase, spaces to hyphens, special characters stripped. You can link inside the same file:

markdown

## Installation
...
## API
...
[Jump to API](#api)

For longer READMEs, add a small **table of contents** at the top with links to each ## section—readers skim faster, and you look organized on first open.

When headings repeat (for example two sections titled “Usage”), GitHub deduplicates anchors by appending -1, -2, and so on—preview your file on GitHub and hover the heading chain icon to confirm the slug if a TOC link fails.

**Task lists** (- [ ] / - [x]) render as interactive checkboxes in issues and pull requests; in plain README files they still display, which is handy for public roadmaps:

markdown

- [x] Core API
- [ ] GraphQL layer

Building tables visually? Use the Markdown Table Generator. Converting an old HTML doc into README-friendly Markdown? Try the HTML to Markdown converter or Paste to Markdown for rich-text paste.

How to Use Markdown in Your GitHub README

The essentials (headings, bold, lists, code)

Tables in GitHub Markdown

Badges and shields

Linking to sections within the README

SiteSupport Team

Related Articles

How to Migrate a WordPress Site to Markdown

Best HTML to Markdown Converters in 2025

Continue Exploring This Topic

Markdown Table Generator

HTML to Markdown Converter

Paste to Markdown Converter

Want AI-powered customer support?