MarkdownPaper Open reader

Guide

What is a README file?

A README is a text file that explains a project: what it is, how to install it, and how to use it. It sits in the top folder of the project, and its name asks you to read it first. Most READMEs today are called README.md, which means they are written in Markdown.

You write

# weather-cli

Shows today's weather in your terminal.

## Install

    npm install -g weather-cli

## Usage

    weather london

You see

weather-cli

Shows today's weather in your terminal.

Install

npm install -g weather-cli

Usage

weather london

That is a complete, if short, README. Someone who finds the project knows what it does and how to start in ten seconds.

3 min read7 sectionsUpdated 1 Oct 2026

On this page

Why it is called README

The name is an instruction: read me before anything else. Software has shipped with a file called README since the 1970s, long before the web. The capital letters were a way to make it stand out at the top of a folder list.

Why .md

The .md ending means the file is written in Markdown. Markdown is plain text, so the file still reads well as it is, but sites like GitHub turn it into a formatted page with headings, lists, links and code blocks. You will also see README.txt for plain text and README.rst for another format, but .md is by far the most common.

Where GitHub shows it

When you open a repository on GitHub, the README.md in the top folder is shown below the list of files. It is the front page of the project. GitHub also looks for a README in a docs folder or a .github folder, and every folder can have its own README, shown when you open that folder.

Your GitHub profile can have one too: make a repository with the same name as your username and put a README.md in it.

What goes in one

There is no fixed rule, but good READMEs answer the same questions in the same order:

  1. What is it? One or two sentences.
  2. Why would I want it? The problem it solves.
  3. How do I install it?
  4. How do I use it? The smallest working example.
  5. How do I get help or contribute?
  6. What is the license?

Small projects need only the first four. The guide on how to write a good README goes through each part and has a template to download.

Who reads it

More people than you think: someone deciding whether to use your project, a new teammate on their first day, you in six months, and more and more often an AI coding assistant reading it to understand the code. A clear README helps all of them.

Questions

Is README.md case sensitive?

On most computers file names are case sensitive, so the exact name matters to some tools. README.md in capitals is the convention, and GitHub finds it whatever the case, but sticking to the convention avoids surprises.

Do I need a README?

For anything you share, yes. Without one, people have to read the code to find out what the project does, and most will not.

How do I open a README.md file?

Any text editor shows the text. To read it formatted, open it in a Markdown reader, or see the README viewer for local files and GitHub links.

Can a README have images?

Yes. Use Markdown image syntax with a path to an image in the project, like ![Screenshot](docs/screenshot.png). See how to add an image in Markdown.

Next