How to Write a GitHub README

A good GitHub README answers the questions a new visitor has first: What does this project do? How do I install and use it? How can I contribute, and what are the project's terms? This guide explains what to include in a useful README.md, how to format it with Markdown, and how to keep it accurate as your project changes.

What is a GitHub README?

A README is the project's front-page documentation. GitHub displays a repository's README.md below its file list, rendering Markdown so visitors can quickly scan the purpose, setup, and usage. It is often the first place users, contributors, and teammates look for project-specific instructions.

A README is not a substitute for detailed documentation when a project needs it. Treat it as a clear starting point: explain the essentials and link to deeper guides where necessary.

What to include in a GitHub README

1. Project name and summary: State what it does, who it is for, and the problem it solves.
2. Features or demo: Highlight useful capabilities and include a screenshot or live demo when that helps explain the project.
3. Prerequisites and installation: List required software and provide steps that work from a fresh clone.
4. Usage: Show a real example of how to run or use the project and what a user should expect.
5. Configuration: Document required environment variables or settings without publishing secret values.
6. Contributing and support: Explain how to report a problem, propose changes, or get help.
7. License and credits: Link to the license and acknowledge important dependencies or sources where appropriate.

Not every repository needs every section. A small script may only need a summary, one command, and a license; a reusable application may need setup, configuration, screenshots, and contribution instructions.

Start with a clear project title and overview

Begin with a single top-level heading containing the project name. Follow it with one or two direct sentences describing the project and its intended audience. Be specific: “A command-line tool that converts CSV files to JSON” tells a visitor more than “A useful utility.”

Add badges only when they provide trustworthy, maintained information, such as a build status or release version. A badge should link to its source or documentation when possible. Avoid decorative badges that make the project look more active or supported than it is.

Write installation steps people can follow

State the supported runtime or tools, then show the exact commands needed to install and start the project. For example, a Node.js project might document commands like these, adapted to its actual package scripts:

git clone https://github.com/OWNER/REPOSITORY.git
cd REPOSITORY
npm install
npm run dev

Replace example values with your real repository and commands. Do not copy generic steps that do not match the project. If setup requires configuration, explain how to create it from a safe sample such as .env.example, and never include real API keys, passwords, or other credentials in the README.

Add a useful usage example

Show the smallest meaningful example that demonstrates the project's main feature. Include expected output when it is useful, and label placeholders so readers do not mistake them for literal values. For a command-line app, an example might look like:

tool-name input.csv --format json
# Writes the converted data to output.json

Test the commands before publishing. A quick check is to follow the README from a fresh clone or ask someone unfamiliar with the project to try it and note where they get stuck.

Format your README with Markdown

Use headings in a logical order, fenced code blocks for commands, and short paragraphs for explanations. Keep heading levels hierarchical instead of choosing a heading size just for its appearance. Descriptive link text is easier to understand than phrases such as “click here.”

# Project name

One sentence explaining what the project does.

## Installation

```bash
npm install
```

## Usage

Describe how to use the project and link to further documentation.

Make screenshots and links accessible

Screenshots can quickly communicate what a visual project does. Add relevant images to the repository or use a stable, project-approved hosting location. Write useful alternative text that explains what the image conveys, and do not rely on an image as the only place important instructions appear.

Verify internal links, badges, demo links, and image paths after moving or renaming files. Relative links can keep documentation within the repository, while external links should point to maintained pages rather than temporary resources.

Common README mistakes to avoid

• Leaving template placeholders, broken links, or setup commands that no longer work.
• Describing features that are planned as if they already exist.
• Pasting secrets, private configuration, or sensitive personal information into documentation.
• Using a wall of text instead of headings, lists, and short examples.
• Omitting a license while implying that others may reuse the code. Add an appropriate license file if you want to grant permissions; do not assume public visibility alone grants reuse rights.

Frequently asked questions

What should a GitHub README include?

At minimum, explain what the project does and how to get started. Add usage, configuration, contribution, support, and license details when they apply to your project.

Should I use a README template?

A template can help you remember common sections, but remove anything irrelevant and replace every placeholder. Accurate project-specific instructions are more useful than a long generic checklist.

Is README.md written in Markdown?

Yes. GitHub renders .md files using Markdown, including headings, lists, links, images, and fenced code blocks.