Last Updated: May 15, 2019
· jjperezaguinaga

How to make beautiful Github README


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.


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

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

<a name="team-members"></a>Team Members

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?

6 Responses
Add your response


Any chance you could throw up a sample template to work from? That's a great list, but it'd be awesome, especially for people like me who don't write markdown, to have a base to start from. Thanks!

over 1 year ago ·

I second what Kyle said!

over 1 year ago ·

To auto-generate the Markdown TOC, see the Sublime3 plugin: https://sublime.wbond.net/packages/MarkdownTOC
It regenerates (on save) an unordered list based on the headings. I would suggest a config of "MarkdownTOC autolink=true depth=2 bracket=round" for Github .md-style files.

over 1 year ago ·

I have put a lot of work into mine if anyone wants to get any ideas from it: https://github.com/ryanoasis/vim-webdevicons/blob/master/readme.md

over 1 year ago ·

Here is another one that has taken various advice and carefully crafted: https://github.com/ryanoasis/nerd-fonts

over 1 year ago ·

The food is high healthy protein at 24%, as well as also consists. https://medium.com/@getwetdogfood Unsurprisingly, they likewise do much better with small-bite foods.

8 months ago ·