How to Write a Great README.md for Your GitHub Project (2025)
Learn how to create professional README files that make your GitHub projects stand out. Includes badges, templates, and a free generator tool.
Your README is the first thing people see when they visit your GitHub repo. A good one can be the difference between someone starring your project or clicking away.
Here's how to write READMEs that actually get people interested.
Why Your README Matters#
The README is your project's landing page. It answers three critical questions:
- What is this? — What does your project do?
- Why should I care? — What problem does it solve?
- How do I use it? — How do I get started?
If you can't answer these in the first 30 seconds of someone reading your README, you've lost them.
Anatomy of a Great README#
1. Project Title & Badges#
Start with your project name and status badges:
# My Awesome Project
Badges communicate professionalism and project health at a glance. Common badges include:
- npm version — Shows the package is published
- License — Tells users how they can use it
- Build status — Shows the project is maintained
- Downloads — Social proof
- TypeScript — Language/framework badges
2. One-Line Description#
Right after badges, add a single sentence that explains what your project does:
A fast, lightweight library for handling date formatting in JavaScript.No buzzwords. No marketing speak. Just what it does.
3. Features List#
Bullet points work best here. Keep it scannable:
## Features
- Zero dependencies
- Tree-shakeable ESM exports
- TypeScript support out of the box
- 10x faster than moment.js
- Works in Node.js and browsers4. Installation#
Make it copy-paste ready:
## Installation
npm install my-project
# or with yarn
yarn add my-project
# or with pnpm
pnpm add my-project5. Quick Start / Usage#
Show the simplest possible example that demonstrates value:
## Usage
import { formatDate } from 'my-project';
const formatted = formatDate(new Date(), 'YYYY-MM-DD');
console.log(formatted); // 2025-01-28Don't show every feature. Show the most common use case.
6. API Reference (Optional)#
For libraries, include a brief API reference or link to full docs:
## API
### formatDate(date, format)
Formats a date according to the specified format string.
| Parameter | Type | Description |
|-----------|------|-------------|
| date | Date | The date to format |
| format | string | Format string (e.g., 'YYYY-MM-DD') |
Returns: `string`7. Contributing#
If you want contributions, make it easy:
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the project
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request8. License#
Always include a license:
## License
MIT © [Your Name](https://github.com/yourusername)README Template#
Here's a complete template you can copy:
# Project Name
One-line description of what this project does.
## Features
- Feature 1
- Feature 2
- Feature 3
## Installation
npm install project-name
## Usage
import { something } from 'project-name';
// Example code here
## API
Brief API documentation or link to full docs.
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## License
MIT © Your NameCommon README Mistakes#
1. Too Much Information#
Your README isn't your full documentation. Link to docs for details.
2. No Installation Instructions#
Never assume people know how to install your project.
3. Outdated Examples#
Nothing worse than copy-pasting an example that doesn't work. Keep examples updated.
4. Wall of Text#
Use headings, bullets, and code blocks. Make it scannable.
5. No License#
Without a license, people legally can't use your code. Always include one.
Shields.io Badge Cheat Sheet#
Here are the most common badges:
# npm version
# License
# Build status
# Downloads
# GitHub stars
# TypeScript
# PRs Welcome
Generate Your README Automatically#
Don't want to write all this by hand? Use our free README generator:
It includes:
- One-click badge generation
- Auto-formatted sections
- Live preview
- Copy or download
No signup required.
Beyond the README#
A great README is just the start. As your project grows, you'll need:
- Full documentation — Tutorials, guides, API reference
- Changelog — Track what changed between versions
- Contributing guide — Detailed contribution instructions
- Code of conduct — Community guidelines
If you're ready to level up from a README to full documentation, try Dokly — it's free to start and gives you a complete docs site with MDX, search, and AI writing assistance.
Written by Gautam Sharma
Building Dokly — documentation that doesn't cost a fortune.
Follow on Twitter →Keep reading
How to Make Your Documentation AI-Agent Friendly (2026 Guide)
Learn how to optimize your developer documentation for AI agents like Claude, ChatGPT, and Cursor. Practical tips for llms.txt, structured content, and machine-readable docs.
4 min read
Cheapest Documentation Platforms in 2026 (Honest Comparison)
Looking for affordable documentation tools? We compare the cheapest options in 2026 — from free tiers to budget-friendly paid plans. No BS, just real pricing.
6 min read