How to Write a Great GitHub README in Markdown

Your README is the front door of your project. On GitHub, it's the first thing a visitor sees — often the only thing they read before deciding whether to star, install, contribute, or move on. A useful README explains what the project does, how to run it, and which limitations matter. Writing strong github readme markdown isn't about fancy formatting — it's about answering the right questions, in the right order, with copy-pasteable examples. This guide walks through the sections that matter, the structural habits that make a README scannable, and a skeleton you can drop into any project today.

Why the README matters so much

A README does three jobs at once, and a good one serves all three audiences:

• Visitors need a short explanation of what the project does near the top.
• Potential collaborators need to know what the project does, how to run it, and where help is needed before they'll open a pull request.
• Future you will forget how to install your own tool in six months. The README is the note you leave for yourself.

GitHub displays a repository README to visitors when it is in a recognized location. Package registries and other platforms have their own rendering rules. Treat the README as the entry point to your documentation and check it at each place you publish.

The essential README sections

Most great READMEs share the same backbone of sections. You don't need all of them for every project, but you should know which ones you're skipping and why.

Title and badges

Lead with the project name as an # H1, followed by a row of badges (build status, version, license, downloads). Use status badges only when they reflect the real project; a static badge is not evidence of usage or endorsement. The example below uses placeholder repository names.

# my-awesome-tool

![build](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)
![npm](https://img.shields.io/npm/v/my-awesome-tool)
![license](https://img.shields.io/github/license/user/repo)

Short description

One or two sentences explaining what the project is and who it's for. Avoid jargon. If a non-expert can't understand the first sentence, rewrite it.

Demo GIF or screenshot

A short animated GIF or screenshot communicates more than three paragraphs of text. Show the tool doing its core thing. Keeping the image in an assets/ or docs/ folder lets you version it with the document. Check the relative path after moving files or changing branches.

Installation

Copy-pasteable install commands. One block per package manager is ideal.

npm install my-awesome-tool
# or
yarn add my-awesome-tool
# or
pnpm add my-awesome-tool

Usage

A minimal working example. Show the smallest snippet that produces a real result — the "hello world" of your tool. Then layer in advanced options below.

import { transform } from 'my-awesome-tool';

const result = transform('# Hello');
console.log(result);

Configuration

If your tool takes options, document them in a table rather than a wall of prose. Tables are scannable; paragraphs are not.

Option	Type	Default	Description
format	'html' | 'text'	'html'	Output format.
strict	boolean	false	Throw on invalid input.
timeout	number	5000	Max processing time in ms.

Contributing

Tell people how to contribute: where issues live, how to run tests, any code-style rules, and whether PRs are welcome. Link to a CONTRIBUTING.md if you have one.

License

Name the license (MIT, Apache-2.0, etc.) and link to the LICENSE file. State the actual license and point to the corresponding file; do not insert a license name that the project has not adopted.

Structural tips that make a README scannable

Section order matters as much as section content. These habits consistently improve README readability:

• Lead with a one-liner. The very first line after the title should explain what the project does. Don't bury it under a logo or a badge wall.
• Use a demo before prose. A GIF or screenshot in the first screenful of content does more than three paragraphs of explanation.
• Keep install steps copy-pasteable. Each command in its own fenced block, ready to paste into a terminal. No $ prefixes that break copy-paste.
• Use tables for options and flags. A grid of name/type/default/description beats a bulleted list every time.
• Progressively disclose complexity. Quickstart first, advanced configuration later. A reader who only reads the top third should still understand the project.
• Keep headings shallow. Stick to ## and ###. Deeply nested headings are a sign the README is trying to be a full manual — split that into docs/.

Tip: Write your README for the reader who will spend 30 seconds on it, not the one who will spend 30 minutes. The 30-second reader is far more common, and if you win them, the 30-minute reader will find what they need anyway.

A copy-pasteable README skeleton

Here's a complete skeleton you can drop into a new project and fill in. It uses GitHub-flavored Markdown features (badges, tables, fenced code, task lists).

# Project Name

![build](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)
![license](https://img.shields.io/github/license/user/repo)

> One-sentence description of what this project does and who it's for.

## Features

- Fast and dependency-free.
- Works in the browser and Node.
- Fully typed with TypeScript.

## Demo

![demo](docs/demo.gif)

## Installation

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

## Quick start

```js
import { run } from 'project-name';

const output = run('input');
console.log(output);
```

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `verbose` | `boolean` | `false` | Print extra logs. |
| `format` | `'json' \| 'text'` | `'json'` | Output shape. |

## Contributing

PRs welcome! Please open an issue first to discuss changes.

```bash
git clone https://github.com/user/repo
cd repo
npm install
npm test
```

## License

[MIT](LICENSE)

Drop this into README.md, fill in the blanks, and you have a README that already beats most of the projects on GitHub.

Common README mistakes to avoid

Review your draft for these common problems:

• No install steps. A description with no npm install / pip install / clone instructions leaves the reader guessing. Always include copy-pasteable install commands.
• Wall of text. Long unbroken paragraphs with no headings, code, or images. Nobody reads them. Break content up with ## sections, code blocks, and tables.
• Broken images. Screenshots hosted on external services that go offline, or relative paths that break outside the default branch. Commit images to the repo.
• Stale badges. A red "build failing" badge on the homepage is worse than no badge. Either fix the build or remove the badge.
• No license. State the permissions the project actually grants. Choose the license with the project owner and include its full terms.
• Assuming knowledge. Skipping the basics ("obviously you need Docker and PostgreSQL configured") loses new users. Link to prerequisites instead.
• Outdated examples. A code sample that doesn't match the current API is worse than no sample. Re-run your examples in CI if you can.

For a deeper reference on the Markdown syntax used throughout a README — tables, task lists, fenced code, autolinks — the GitHub-flavored Markdown guide covers everything GitHub renders beyond plain Markdown.

Preview your README before you push

A README full of typos, broken tables, or mis-rendered code blocks makes a bad first impression — and these are all things you can catch before pushing. Two habits help:

1. Preview locally. Paste your README.md into the MD viewer to see exactly how GitHub will render it — headings, tables, code highlighting, and all. You'll spot a broken table or an un-rendered link in seconds.
2. Edit and iterate in one place. The in-browser editor lets you tweak the Markdown on the left and watch the rendered output update live on the right. Fix the source, watch the preview, copy it back when you're done.

This catches the formatting bugs that GitHub's reviewer feedback loop is too slow for. It's much faster than pushing a commit just to see if a table renders correctly.

Key takeaways

• The README is your project's front door — it decides whether visitors install, star, or contribute.
• Use a consistent backbone: title + badges, one-line description, demo, install, usage, configuration, contributing, license.
• Structure for scannability: lead with a one-liner, show a demo early, keep install steps copy-pasteable, and use tables for options.
• Avoid the classics: missing install steps, walls of text, broken images, stale badges, and no license.
• Always preview before you push — a rendered view catches formatting bugs that raw text hides.

Ready to see how your README will look on GitHub before you commit? Paste it into the MD viewer and catch every formatting bug in seconds.