How to make the perfect Readme.md on GitHub
By: Sayan Mondal
Tags: Planning, Markdown, Repository Pattern, Readme, Github

From providing access control and several collaboration features such as bug tracking, feature requests, task management, and wikis for every project, we all know how cool GitHub really is. But let’s face it, even if you have the generation’s best project lying down in your profile, without an attractive and a detailed readme, it gets unnoticed.

Every time when you create a repository on GitHub there are two options at the bottom.

Add a readme — This creates a default readme with just a basic description. Add a license — This has a variety of licenses to choose from depending on the type of software you are making.

So what is this Readme.md file?

A Readme file gives the user(who visits your repository) a brief idea about what the project is about, which language it has used, what are the terms and conditions, licensing, how many forks/stars the repository has got, what your project can do, screenshots of your running application, etc

The extension .md stands for Markdown which is a lightweight markup language with plain text formatting syntax. It’s a very simple language used to create beautiful and presentable readme files for GitHub.

How should you write it?

You need to follow a certain syntax pattern to get the correct Markdown script as your desired output.

Header

# H1

## H2

### H3

#### H4

##### H5

###### H6



Alternatively, for H1 and H2, an underline-ish style:



Alt-H1

======



Alt-H2

------

Emphasis

Emphasis, aka italics, with *asterisks* or _underscores_.



Strong emphasis, aka bold, with **asterisks** or __underscores__.



Combined emphasis with **asterisks and _underscores_**.



Strikethrough uses two tildes. ~~Scratch this.~~

Lists

1. First ordered list item

2. Another item

⋅⋅* Unordered sub-list.

1. Actual numbers don't matter, just that it's a number

⋅⋅1. Ordered sub-list

4. And another item.



⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).



⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅

⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅

⋅⋅⋅(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)



* Unordered list can use asterisks

- Or minuses

+ Or pluses

Links

[I'm an inline-style link](https://www.google.com)



[I'm an inline-style link with title](https://www.google.com "Google's Homepage")



[I'm a reference-style link][Arbitrary case-insensitive reference text]



[I'm a relative reference to a repository file](../blob/master/LICENSE)



[You can use numbers for reference-style link definitions][1]



Or leave it empty and use the [link text itself].



URLs and URLs in angle brackets will automatically get turned into links.

http://www.example.com or <http://www.example.com> and sometimes

example.com (but not on Github, for example).



Some text to show that the reference links can follow later.



[arbitrary case-insensitive reference text]: https://www.mozilla.org

[1]: http://slashdot.org

[link text itself]: http://www.reddit.com

Images

Here's our logo (hover to see the title text):



Inline-style:

![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")



Reference-style:

![alt text][logo]



[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"

Visit this link for in-depth knowledge on how to write a markdown sheet

(All the syntax have been referenced from: Markdown Cheatsheet by Adam Pritchard)

Photo from MarkdownGuide.org

Now that you’ve created a basic readme file, Let’s come to the fun part

Let’s buff up our designing skills and make this readme look catchy and attractive, shall we?

First things first, we’ve already crafted up the descriptions, getting started and the details now it’s time to add some working demonstrations(in the form of gif) as well as screenshots of the product. It may or may not be helpful sometimes, It totally depends on the project you are making.

If it is an app or a website, It’s a better idea to have a prototype out there but if it’s simply a code it doesn’t make sense to have a screenshot right? So think for yourself and do whatever you feel is right for your project.

Inserting Screenshots and gifs

It's always a better idea to show your working prototype side by side rather than putting one image per paragraph, For instance in this project, It's better to have all the images lined up together as in -

Rather than having all the images and gifs standing there one below the other. And also its always better to have gifs since it better expresses your work and also lets the reader know how the application actually looks like from a user’s perspective.

How to put the images side by side?

One approach could be using the <img> tags as used in HTML, where you can set the width and the height of the image to be placed in the readme. It's recommended changing only the width so as to maintain the aspect ratio of the image, else if you want it customized? Feel free to explore with the height as well.

To have multiple images next to each other all you need to do is put them right after you finish writing the markdown of the previous one.

NOTE: Whatever image you choose to have in your readme file, make sure you also have that uploaded in your repository as well. Or you could reference the link address from anywhere, that’d work too.

How to add badges

Badges are a really important part of any GitHub readme as it not just tells you but also the reader how many forks this repository has, how many issues have been raised till now, and also gives away a lot of valuable information for the user to decide whether they’d want to contribute to this repository or not.

Some set of badges I use in a specific repository called ‘Tic Tac Toe’ looks something like this.