What is a README file on GitHub?

GitHub is one of the most commonly used version control and collaboration software in the development community.

A README file communicates important information about a repository or a project. The file format of README is .md, which stands for Markdown. Markdown is a light markup language that we can easily convert to text.

Why is a README file important?

It is the first thing users see when they land on a repository. The README file is usually shown right below the folders of code.

Contents

The README file is used to show the following:

• the project logo (if it exists)
• the documentation
• table of contents
• a summarized version of what the project is about
• if and how others can contribute
• the author, maintainers, and the contributors

Locating README file

GitHub automatically locates and displays your README file on the front page of the repository if you place it in the repository’s root, a docs folder, or the hidden .github folder.

Example of a README file

An example README is displayed below.

A special README file

One special README file can be configured to show up on your main profile page. You can use it to display facts about yourself, your work, and your projects. This README file should be in the root of a public repository with the same name as your username.