Codecademy Logo

GitHub & Markdown

A GitHub README File

Adding a README file to your GitHub repository is the best way to introduce your project to others. Since it is usually the first thing others see on your repository, it is the best place to explain what your project does, why it’s useful, and how they can get started with it.

Comic with three panels in which a character clones a GitHub project, gets confused trying to use it, and finally realizes after three hours that there’s a README file explaining all of the steps

Writing a Good README file

A good README file in GitHub, at minimum, contains the following elements:

  • Title
  • Description
  • Features
  • How to use
  • Technologies
  • Collaborators
  • License

You can further level up your README file with markdown:

  • Use headers and HTML to format your README and make it easier to read.
  • The headers automatically generate a table of contents on GitHub!
  • Use media, such as images and videos, to make your project look more appealing.
An image of a README on GitHub showing table of contents for the project called "My Awesome Project". The headers include "What does it do?", "Usage" with a "Requirements" subsection, and "License".

Learn More on Codecademy