fy05hq
Last Updated: March 26, 2017
·
39.48K
· jjperezaguinaga
Me 180x180

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
Picture

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):

Picture

(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.

Picture

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!

Picture

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

Say Thanks
Respond

5 Responses
Add your response

10919

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 ·
14202
Ded48c05bb74718afd50531fda13f3be

I second what Kyle said!

over 1 year ago ·
17298
9f9cb186b1189e193e4d2a88b85bccb0

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 ·
21295
Nyan

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 ·
28742
Nyan

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

8 months ago ·
Filed Under