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 great README turns a confusing repo into a welcoming one; a bad README sinks even the best code. 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 decide in ~10 seconds whether your project is worth their time. The top of your README is that 10 seconds.
- 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 renders your README automatically on the repo homepage, in npm packages, on GitHub Explore, and in social link previews. It's also the only Markdown file most people will ever read who didn't go looking for it. Treating it as real documentation — not an afterthought — is one of the highest-leverage things you can do for adoption.
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). Badges come from services like shields.io and give instant social proof.
# my-awesome-tool
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. Host the image in the repo itself (an assets/ or docs/ folder) so the link never rots.
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-toolUsage
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. This is non-negotiable — unlicensed code is, by default, "all rights reserved."
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 intodocs/.
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
> 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
## Installation
```bash
npm install project-nameQuick start
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.
git clone https://github.com/user/repo
cd repo
npm install
npm testLicense
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
After reading hundreds of READMEs, the same problems show up again and again:
- **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.** Without a license file, your project is technically unusable by anyone else. Add one — it takes 30 seconds.
- **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](/blog/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](/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](/#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](/md-viewer) and catch every formatting bug in seconds.Try it in your browser
Open the homepage editor to view, edit, and export Markdown instantly — no install required.