The (or README.rst) is a file in Markdown describing the project, how to install it, how to use it... See

  • ✍️ What's the project's name and goal/description
  • 🧸 How can we install it? Run it? Test it?
    • Add examples (GIF, I/O, demo...)
    • Provide a link to some documentation
  • πŸ“¦ Why have you made this project? Who is your audience?
  • 🌳 Credits, maintainers, contributors, license...

➑️ See also: GitHub - About

A lot of developers are using badges to show some information about the project such as badge. See,, markdown-badges,, and license badges.

There are a few metrics you may also show:

πŸ’‘ On GitHub, you can put the in /docs/.

πŸŽ‰ Fancy GitHub πŸŽ‰

On GitHub, READMES are used for many things other than just the README of a project. For instance, we may use a to populate our profile, or our organization profile.