Back to blog
Guide

How to Write a Perfect GitHub README - Complete Guide

Learn to write professional GitHub README files with badges, installation instructions, code examples, and best practices. Complete guide with templates and examples.

Milind Mishra
Milind Mishra/Creator

How to Write a Perfect GitHub README

A GitHub README is your project's first impression and primary documentation. Write a professional README with clear sections, badges, installation instructions, code examples, and contribution guidelines to attract users and contributors.

Quick answer: A perfect GitHub README includes project title, brief description, badges, installation steps, usage examples, screenshots, and contribution guidelines. Use GitHub Flavored Markdown (GFM) for tables, task lists, and syntax-highlighted code blocks.

Why READMEs Matter

First Impression

Your README is the first thing visitors see on GitHub. A well-written README:

  • Attracts users: Clear explanation of what your project does
  • Encourages contributions: People understand how to help
  • Builds trust: Professional documentation shows quality
  • Improves SEO: GitHub ranks repositories with good READMEs higher

Statistics: Projects with comprehensive READMEs receive 2.5x more stars and 3x more contributions than those without (GitHub data analysis, 2025).

GitHub README Features

  • Auto-rendered: Markdown renders automatically on GitHub
  • GFM support: Tables, task lists, emojis, and more
  • Relative links: Link to files within your repository
  • Images and screenshots: Embed visual assets easily
  • Code highlighting: Syntax highlighting for code blocks

Essential README Sections

1. Project Title and Description

markdown
# Project NameShort, one-sentence description of what your project does.

Best practices:

  • Use # heading for project name (only once per README)
  • Keep description to one sentence (30-50 words)
  • Be specific about what the project does
  • Include main programming language or framework

2. Badges

Badges provide quick information about your project status and quality.

markdown
![License](https://img.shields.io/badge/license-MIT-blue.svg)![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)![NPM Version](https://img.shields.io/badge/npm-v1.2.3-blue.svg)![Downloads](https://img.shields.io/badge/downloads-10k%2Fmonth-blue.svg)

Common badges:

Badge TypeServiceExample URL
LicenseShields.iohttps://img.shields.io/badge/license-MIT-blue.svg
Build StatusGitHub Actions, Travis CI, CircleCIRepository-specific
CoverageCodecov, CoverallsRepository-specific
Versionnpm, PyPI, crates.ioRepository-specific
Downloadsnpm, PyPIRepository-specific
DependenciesDependencies.ioRepository-specific
PRs WelcomeShields.iohttps://img.shields.io/badge/PRs-welcome-brightgreen.svg

3. Table of Contents

Auto-generate or manually create a TOC for navigation.

markdown
## Table of Contents- [Features](#features)- [Installation](#installation)- [Usage](#usage)- [API](#api)- [Contributing](#contributing)- [License](#license)

4. Features

List key features with bullet points or task lists.

markdown
## Features- ✅ User authentication with JWT- ✅ Real-time updates with WebSocket- ✅ Responsive design (mobile, tablet, desktop)- ✅ Dark mode support- ✅ TypeScript for type safety- ✅ Unit and integration tests- ✅ Docker support for easy deployment

5. Installation

Clear, step-by-step installation instructions.

markdown
## Installation### Prerequisites- Node.js 18+ installed- npm or yarn package manager- Git for cloning the repository### Install from npm```bashnpm install my-project

Install from GitHub

bash
git clone https://github.com/username/my-project.gitcd my-projectnpm install

Configuration

Create .env file:

bash
cp .env.example .env

Edit .env with your values:

bash
API_URL=https://api.example.comAPI_KEY=your_api_key_here
### 6. UsageExamples of how to use your project.```markdown## Usage### Basic Example```javascriptimport { Project } from 'my-project';const app = new Project({  apiKey: 'your-api-key',  debug: true});app.start();

Advanced Example

javascript
import { Project } from 'my-project';const app = new Project({  apiKey: 'your-api-key',  config: {    timeout: 5000,    retries: 3  }});await app.initialize();await app.runTask('example-task');

Configuration Options

OptionTypeDefaultDescription
apiKeystring-Your API key (required)
debugbooleanfalseEnable debug logging
timeoutnumber30000Request timeout in milliseconds
retriesnumber3Number of retry attempts
### 7. ScreenshotsVisual demonstrations of your project.```markdown## Screenshots### Dashboard![Dashboard Screenshot](https://raw.githubusercontent.com/username/my-project/main/screenshots/dashboard.png)### User Profile![User Profile Screenshot](https://raw.githubusercontent.com/username/my-project/main/screenshots/profile.png)### Settings![Settings Screenshot](https://raw.githubusercontent.com/username/my-project/main/screenshots/settings.png)

Best practices:

  • Store screenshots in screenshots/ directory
  • Use raw GitHub URLs for reliable embedding
  • Include alt text: ![Alt text](url)
  • Show key features and workflows

8. API Reference

Document your API with tables and code examples.

markdown
## API Reference### Users API#### Get All Users**Endpoint:** `GET /api/users`**Parameters:**| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| page | integer | No | Page number (default: 1) || limit | integer | No | Items per page (default: 10) |**Response:**```json{  "users": [    {      "id": 1,      "name": "Alice",      "email": "alice@example.com"    }  ],  "total": 100,  "page": 1}

Create User

Endpoint: POST /api/users

Request Body:

json
{  "name": "Bob",  "email": "bob@example.com",  "password": "securepassword"}

Response:

json
{  "id": 2,  "name": "Bob",  "email": "bob@example.com",  "createdAt": "2026-03-07T12:00:00Z"}
### 9. ContributingClear guidelines for contributors.```markdown## ContributingWe welcome contributions! Please follow these guidelines:### How to Contribute1. Fork the repository2. Create your feature branch (`git checkout -b feature/amazing-feature`)3. Commit your changes (`git commit -m 'Add amazing feature'`)4. Push to the branch (`git push origin feature/amazing-feature`)5. Open a Pull Request### Development Setup```bashgit clone https://github.com/username/my-project.gitcd my-projectnpm installnpm run dev

Running Tests

bash
# Run all testsnpm test# Run tests in watch modenpm run test:watch# Run tests with coveragenpm run test:coverage

Code Style

  • Follow existing code style
  • Use Prettier for formatting
  • Run npm run lint before committing
  • Add tests for new features

Commit Messages

Follow conventional commits:

feat: add user authenticationfix: resolve login timeout bugdocs: update API documentationtest: add unit tests for user service
### 10. LicenseSpecify your project's license.```markdown## LicenseThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Common licenses:

LicenseDescriptionWhen to Use
MITPermissive, simpleMost open source projects
Apache 2.0Permissive, patent protectionLarge projects, companies
GPLv3Copyleft, viralFree software projects
BSDPermissiveAcademic or research projects

11. Acknowledgments

Credit contributors and dependencies.

markdown
## Acknowledgments- Thanks to all contributors who made this project possible- Built with [Express](https://expressjs.com/), [React](https://reactjs.org/)- Icons from [FontAwesome](https://fontawesome.com/)- Inspired by [Similar Project](https://github.com/other/project)

Complete README Template

markdown
# Project NameShort, one-sentence description of what your project does and why it's useful.![License](https://img.shields.io/badge/license-MIT-blue.svg)![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)![NPM Version](https://img.shields.io/badge/npm-v1.2.3-blue.svg)## Table of Contents- [Features](#features)- [Installation](#installation)- [Usage](#usage)- [API](#api)- [Contributing](#contributing)- [License](#license)## Features- ✅ Feature 1- ✅ Feature 2- ✅ Feature 3- ✅ Feature 4## Installation### Prerequisites- Node.js 18+- npm or yarn### Install```bashnpm install my-project

Configuration

bash
cp .env.example .env

Edit .env with your configuration.

Usage

Basic Example

javascript
import { Project } from 'my-project';const app = new Project();app.start();

Configuration Options

OptionTypeDefaultDescription
apiKeystring-Your API key
debugbooleanfalseEnable debug logging

Screenshots

Screenshot

API Reference

Example Endpoint

Endpoint: GET /api/resource

Response:

json
{  "data": "example"}

Contributing

  1. Fork the repository
  2. Create your feature branch
  3. Commit your changes
  4. Push to the branch
  5. Open a Pull Request

See CONTRIBUTING.md [blocked] for details.

License

This project is licensed under the MIT License - see the LICENSE [blocked] file for details.

Acknowledgments

  • Thanks to contributors
  • Built with
  • Inspired by 
## README Best Practices### 1. Keep It Concise```markdown# Bad - Too verbose# Project NameThis is a very long-winded description that goes on and on and doesn't get to the point quickly enough to keep the reader interested in learning more about what this project actually does and why they should care about it.# Good - Concise and clear# Project NameSimple, fast markdown editor with live preview and Monaco syntax highlighting.

2. Use Relative Links

markdown
# Bad - Absolute links[Documentation](https://github.com/username/project/tree/main/docs)[Contributing](https://github.com/username/project/blob/main/CONTRIBUTING.md)# Good - Relative links[Documentation](docs/README.md)[Contributing](CONTRIBUTING.md)

3. Add Code Examples

markdown
# Bad - Text-only descriptionTo install, run the install command with npm, then configure your environment variables.# Good - Code examples```bashnpm installcp .env.example .env
### 4. Use Screenshots```markdown# Bad - No visualsThe dashboard shows user statistics and activity.# Good - With screenshotThe dashboard shows user statistics and activity:![Dashboard](https://raw.githubusercontent.com/username/project/main/screenshots/dashboard.png)

5. Maintain README

Keep your README up-to-date:

  • Update when adding features
  • Update when breaking changes occur
  • Update badges automatically
  • Review quarterly for outdated information

Common README Mistakes

1. No Installation Instructions

Users can't figure out how to install your project.

Fix: Add clear, step-by-step installation section with code examples.

2. No Usage Examples

Users don't know how to use your project.

Fix: Include basic and advanced usage examples with code blocks.

3. Outdated Screenshots

Screenshots don't match current version.

Fix: Update screenshots with each major release.

4. Missing Badges

Users can't quickly assess project status.

Fix: Add relevant badges (license, build, version, etc.).

5. No Contributing Guidelines

Contributors don't know how to help.

Fix: Add CONTRIBUTING.md file or contributing section.

6. Too Technical

README assumes too much prior knowledge.

Fix: Start simple, add advanced sections later. Explain jargon.

README for Different Project Types

JavaScript/Node.js Projects

markdown
# My Node.js ProjectA Node.js package for doing X.## Installation```bashnpm install my-package

Usage

javascript
const myPackage = require('my-package');myPackage.doSomething();
### Python Projects```markdown# My Python ProjectA Python library for X.## Installation```bashpip install my-package

Usage

python
import my_packagemy_package.do_something()
### Go Projects```markdown# My Go ProjectA Go library for X.## Installation```bashgo get github.com/username/my-project

Usage

go
import "github.com/username/my-project"my_package.DoSomething()
### Web Applications```markdown# My Web AppA web application for X.## Deployment### Docker```bashdocker build -t my-app .docker run -p 3000:3000 my-app

Manual

bash
npm installnpm run buildnpm start
## FAQ### How long should a README be?Keep it under 5 minutes reading time. Most users skim; use headings and structure for quick scanning.### Should I include all features?No, highlight key features. Detailed documentation should go in separate files or docs/ directory.### Do I need screenshots?Yes, for UI-heavy projects. For libraries and APIs, code examples are more important.### What if my project doesn't have tests yet?Be honest. Write: "Tests coming soon" or explain testing plans. Don't fake badges.### Can I use HTML in READMEs?Yes, but stick to markdown when possible. Use HTML only for advanced formatting markdown doesn't support.### Should I include a changelog?Yes, add a "Changelog" section linking to CHANGELOG.md. Show recent updates.## Summary**Essential README Sections:**1. Project title and description2. Badges (status, version, license)3. Table of contents4. Features list5. Installation instructions6. Usage examples7. Screenshots (for UI projects)8. API reference9. Contributing guidelines10. License information11. Acknowledgments**Best Practices:**- Keep it concise and scannable- Use code examples, not just text- Include screenshots for visual projects- Maintain and update regularly- Use relative links for internal files- Add badges for quick status info**Avoid:**- Overly long READMEs (>10 minutes to read)- Missing installation or usage instructions- Outdated screenshots or information- Assuming too much prior knowledge- Poorly formatted code examples[Try Your README in Markdown Visualizer](/) — Free Monaco-powered editor with live preview and GFM support.**Data sources:** GitHub README best practices, open source project analysis (2025), industry documentation standards.

Practice

Try it in the editor.

Open Markdown Visualizer and test the ideas from this article in a live editor with instant preview.

Open Editor