Write A Github README.md

Below is a basic readme profile to help you get started, after you write a few and you start to get comfortable you will begin to write and structure the readme files how you want based on your perception of best practice. This is not at all comprehensive just a start and what I was looking for when I started.


Start with the title of your project followed by a description, add some insight into the project, what it does and why it was created, what problems it solves. Name some of the notable features and others you want to implement in the future, this section is the showcase of your project.


Add instructions on how to install and setup your project. An easy way for me to write this section is to clone my own projects and start fresh trying to get them up and running on my machine. I add instructions as I go through each step on how to get the project setup.

If using Rails add dependencies like ruby version and include instructions like bundle install , instruct as if you were teaching somebody who has never programmed before that way you can include all levels of skill.

Here you can add examples, pictures, gifs, videos.

If project uses an API you could note that here as well, if using a server how to get the server running.

If any authentication like usernames, passwords, keys, secrets, or credentials are needed or how to receive them should also be added here.


Dispense instruction along with some examples on how to use the project. A step by step guide so users can follow and reference back to in case they run into any problems.

Here you can also add examples, pictures, gifs, videos. Visual aids will help anyone along if they get stuck or just need a reference to how the project should act.

Another thing to note if there are examples of code if the project is a library.

//Exampleimport ProjectNameProjectName.createsProfile(userName, age)=> {name: userName, age: age)


This section should contain some instruction on how to contribute to the project

//ExamplePull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.Please make sure to update tests as appropriate.

For larger community projects or for more specific guidelines add a contributing guideline, use resources like Contributor Convenant which is a code of conduct for open source and other digital commons communities and githubs guide for contributing.


Add and team members or contributors in this section, add links to their githubs, portfolios, linkedIn, social media, etc.

Add links to tutorials, blogs, or any resources you want noted that helped you develop the project.

Help show appreciation and build your network.


Most README files contain a license which tell other developers what they can and cannot do with your repository. Licenses are chosen based on the project along with how and what contributions you want.

To help you choose license you can navigate to https://choosealicense.com/, this will make it a little easier to decide on what license is best for your project.

example: MIT

The primary terms and conditions of the MIT license are to grant permissions and indemnify developers for future use. Specifically, it grants any person who obtains a copy of the software and associated files the right to use, copy, modify, merge, distribute, publish, sublicense, and sell copies of the software.


  • Badges: A way to let other developers know what you’re doing, Check out the badges hosted by shields.io.
  • Tests: If you have tests written for your project you can add a section that describes how to use them and add their own, also confirms project is working or needs help.
  • List of Awesome READMEs: https://github.com/matiassingers/awesome-readme

Markdown CheatSheet

Headers begin with a # followed by a space and then the Title
# This Rocks! this creates the largest header H1, to create smaller headers add another # ## Still Rocks But now H2

Create a line with 3x underscores ___ , dashes---, or asterisks ***

Code block:
Code Blocks are created with 3X back quote``` and ended with three more ```

Code wanted in code Block

Inline code:
Code written inline with a sentence is started and ended with backquote `

` inline code written here `

To add a link add a word inside brackets followed by a url inside parentheses

[statement or whatever word you want](www.linktothing.com)

Bulleted list:
A bulleted list is started with an asterisks * followed by a space and then the statement.

* first 
* nested list
* second
* nested list
* nested list
* third
* nested list

Ordered list:
An ordered list is started with a number followed by a space and then the statement.

1. first 
* nested list
2. second
* nested list
* nested list
3. third

Add emojis to brighten up your README.
On mac push control + command + spacebar to bring up selectable emojis.
On windows Simply press the Windows key and the period button.

Add Image, Gif, Video!:
To add a picture, gif, or video us format below, it is similar to the link format with the explanation point at the beginning. This will post a gif or pic or video. You can easily do a search for an online gif maker, screen to gif software to make your own gifs also.

![Alt Text](https://media.giphy.com/media/vFKqnCdLPNOKc/giphy.gif)

As always thanks for reading.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store