Most GitHub repos fall into one of two categories. The first has no README at all — just a pile of files and a commit log. The second has a README that's either a wall of text nobody reads past the first paragraph, or a half-filled template where the author replaced the headings but left placeholder content like "this project is powerful and flexible."
A well-written README serves three audiences simultaneously: users who want to know whether this solves their problem and how to get it running, contributors deciding whether to spend time on your project, and search engines indexing your repo for discovery. Getting all three right isn't complicated, but it does require some deliberate structure.
The anatomy of a good README
Project name and one-line description (H1)
Your repo already shows the project name, but a README H1 lets you frame it with context. The description directly under it should be one sentence that explains what the thing does, not what it's built with.
Bad: "A powerful and flexible tool built with React and Node.js." Better: "CLI tool that converts a folder of markdown files into a searchable static site."
Badges
Build status, version, license, and test coverage. Badges signal at a glance whether a project is actively maintained and whether it's safe to depend on. Put them on the line right after your description.
Shields.io generates these for free. Don't skip them — a broken build badge is less damaging than no badge at all, because at least it's honest.
What it does (2-3 sentences max)
Expand on the one-liner with just enough detail to answer "is this what I'm looking for?" Mention the primary use case, any notable constraints, and who it's designed for. Cut anything that starts to sound like marketing copy.
Quick start / installation
This section is the most important part of any README. Make it the thing someone can copy-paste and have running in under two minutes. Use fenced code blocks with the correct language identifier.
npm install your-package
If setup requires more than one command, number the steps. If it requires environment variables, show the exact variable names and where to put them. Don't make anyone guess.
Usage with code examples
Show a working example of the most common use case. Not the most impressive use case — the most common one. The example should demonstrate solving an actual problem, not just calling an API method with placeholder arguments.
const tool = require('your-package');
const result = tool.convert('./content', { output: './dist' });
console.log(`Built ${result.pages} pages in ${result.ms}ms`);
If the tool has a CLI, show that too. Many tools have both programmatic and CLI interfaces and only document one.
Configuration options
A table is the most scannable format for configuration. Include the option name, type, default value, and a one-line description.
| Option | Type | Default | Description |
|---|---|---|---|
| `output` | string | `./dist` | Output directory for built files |
| `clean` | boolean | `false` | Delete output directory before building |
| `watch` | boolean | `false` | Rebuild on file changes |
Contributing guide
At minimum, tell people how to run the project locally and how to submit a pull request. A link to a separate CONTRIBUTING.md is fine — but don't omit this section entirely. Without it, contributors don't know whether you accept PRs, what your testing requirements are, or how to set up a dev environment.
License
State the license name clearly. Link to the full license text in a LICENSE file. Omitting this makes your project legally ambiguous for anyone who wants to use it in a commercial context. MIT and Apache 2.0 are the two most permissive common choices.
Common mistakes to avoid
No screenshots for visual tools. If your project has a UI, a screenshot above the fold is worth more than three paragraphs of description. The caveat: screenshots go stale when the UI changes. If you add them, commit to keeping them current, or use a recording tool that generates them automatically.
Table of contents on short READMEs. A TOC makes sense for READMEs over 500 lines. Adding one to a 200-line README just pushes the actual content further down the page.
Copying the template without editing it. "This project is maintained with ❤️ by contributors" is not useful information. Delete template boilerplate that you didn't intentionally fill in.
Vague capability descriptions. "Powerful", "flexible", "easy to use" — these words appear in every README and communicate nothing. Replace them with specific capabilities. "Converts 10,000 markdown files in under 3 seconds" is useful. "Fast and powerful markdown processing" is not.
Missing version compatibility information. If your package requires Node 18+, Python 3.10+, or a specific OS, say so prominently. Discovery during a failed install is frustrating.
Markdown tips specific to READMEs
Code fences with language hints. GitHub highlights syntax for fenced code blocks when you specify the language. Always do this — it makes examples much easier to read.
Relative links to other repo files. Link to CONTRIBUTING.md, LICENSE, and other files using relative paths so they work regardless of how the repo is accessed.
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
Anchor links for long READMEs. GitHub generates anchor IDs for every heading. For a long README, a table of contents with anchor links lets readers jump to the section they need.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
GitHub callout syntax. GitHub supports a callout syntax that renders as a colored block:
> [!NOTE]
> This feature requires Node 18 or later.
> [!WARNING]
> Running this command will delete all files in the output directory.
These are more visible than a plain paragraph and useful for warnings and version requirements. They only render on GitHub, not in every markdown renderer, so use them for supplementary information rather than critical content.
Using a generator as a starting point
Writing a README from scratch means making structural decisions before you've written any content. A generator handles that part — you get a scaffold with the right sections in the right order, and you fill in the specifics.
md0's README generator produces a template with all the sections above, pre-formatted and ready to fill in. It takes about five minutes to get a solid first draft that you can then refine. The output is clean markdown you can paste directly into your repo.
Generate a README skeleton instantly with md0 README Generator — free, no signup.