How to make beautiful Github README

Introduction

When I create a Github repo, I try to make sure it's readme has at least one of the following elements:

• An introduction (What's the project about?)
• Table of contents (List me all your readme, so I can skim it and see if I'm interested or is what I'm looking for)
• Some design love (A logo, icon, teaser or screen, README's with images look so much better.

Example

How to... make an introduction

No brainer, but make sure it's an introduction, the same way papers have an abstract. I usually go for the following syntax:

# Project Name
> Abstract of the project or small introduction of what the project is about
<hr>

The first uses the "#" tag, followed by the blockquote ">" tag and finally an horizontal line to separate it. Use the < hr > tag (yeah, markdown supports it! I separated it here because Coderwall parses it).

How to... make a table of contents.

Example (works in coderwall too, test it!) -

# Table of Contents
* [Team Members](#team-members)

# <a name="team-members"></a>Team Members
* "J. Jesus. P. Aguinaga" <admin@listforks.com>

Separate the topics your repo talks about with the "#" tag, and then use the following syntax to add your table of contents (if you are lazy like me, go to this Gist and copy the example):

(In Github, you don't need to put the a name tag. It parses the h1 tags with a hyphen, so if they are named the same as your table of contents, you don't need to do anything else. In other places cof Coderwall cof you need to force it with the empty A tag)

How to... add images to a README.

You may not be strange with the familiar of the "!" followed by the alt name property in brackets and then parenthesis with the link.

It's the same in Github, but in order to properly display it properly, you need the RAW file. Create an assets folder, add your images there and use the RAW path in your project. You can even use other Github repo's images as long as they are Publics!

That's all folks. Any other Github beautiful tips?

Related protips:

git checkout remote branch