README a Makeover Story

How to Create and Customize Your Github READMEs

Emmanuel Jose (he/him)
15 min readApr 1, 2021
Particle Banner for my Github Profile: https://github.com/emjose
Banner for my Github Profile: https://github.com/emjose
Table of Contents

Introduction

Once Upon a Time..

I had a Github profile that looked like a big blank page.

After graduating from Flatiron School, my attention became divided, my coding habits stopped, and my Github contribution tiles became as white as my bathroom floor.

Chapter 1

Let’s do a Makeover!

In February 2021, I committed to the #100DaysOfCode Challenge to renew my skills as a developer. Day by day, the green Github tiles started to return, but I had neglected to write READMEs and my Github presence was still sorely lacking.

I was fortunate to have a chat with a recruiter who had seen one of my #100DaysOfCode posts, and he told me:

“We look at your Github more than you think. It gives us a better sense of who you are — what kind of developer you are — more than a resume ever could.

I like your progress, but you should write READMEs since they make good developers stand out.”

That was a big wake up call, but I had a new goal:

I’d give my Github a makeover!

Chapter 2

Design and Inspiration

I started planning out what kind of profile I wanted. I love color gradients/aurora backgrounds, clean lines, neat arrangement, and I like thick and bold typefaces due to my nearsighted vision.

I viewed many Github profile READMEs for inspiration. I viewed my friends’ profiles and all the accounts on Awesome GitHub Profile READMEs.

Here are a few that inspired and acted as springboards for me:

In terms of designing your Github profile README, ask yourself:

  • Does my Github profile represent my personality?
  • What designs and styles authentically represent me?
  • What vibe/mood/aesthetic should my profile convey?
  • What’s my brand and how do I visually communicate it?

Chapter 3

README Setup

It was time to create! Follow along for the steps I took.

First, I watched these YouTube tutorials:

Create a repository with a name matching your Github username.

  • I recommend making your repo private while you make edits. Just remember to make it public when you’re ready.
  • Hold on! Before you press “Create repository,” keep reading!
Creating a Github profile README.
My repo name is “emjose” to match my username. Since my README already exists, there’s an alert.

Initializing a README: Github vs. VS Code

  • If you want to directly edit your profile README on Github, initialize the repo WITH a README.md file. View edits in “Preview changes” tab.
Preview Changes on Github
If you’re editing directly on Github, check edits in the “Preview changes” tab.
  • If you want to create a local folder and then git init with VS Code, initialize the repo WITHOUT a README.md.
  • Why? Because you will create the README.md file in VS Code later (which is what I did).
  • I personally prefer to edit and preview in VS Code, not Github.
  • Working in VS Code is advantageous if you plan to use an Assets folder, images, GIFs, or other media.

Note: In VS Code, I created a stylesheet to experiment with color values, but it’s not being used at all. Github READMEs cannot import stylesheets.

Open Preview option in VS Code.
On VS Code, right-click on the README.md file to preview edits. READMEs cannot use stylesheet files.

Chapter 4

README Formatting

Github README files have an .md extension, which stands for Markdown. Markdown is the syntax for styling all plain text on Github platforms.

It can be argued that Markdown is a superset of HTML, but while Markdown’s strength is its ease of use and legibility, it is not as expressive as HTML.

With that said, you can use HTML and Markdown almost interchangeably in README files. For example:

Comparison of Markdown and HTML.
Comparison of Markdown and HTML Syntax. https://www.markdownguide.org/basic-syntax/

Here are excellent and extensive Markdown syntax resources:

Chapter 5

README Content

So what content should go in your Github Profile README?

You can write or include anything, as long as it’s about YOU.

Here are a few ideas:

  • What you are learning
  • Your interests and fun facts
  • Technologies you want to learn
  • Technologies you are proficient in
  • Social media and contact information
  • Links to your blogs, resume, or a portfolio

Be mindful of what you write — your audience will include:

Non-developers, other developers, recruiters, interviewers, managers

Ask for feedback on your profile README before you publish.

My Github profile intro. https://github.com/emjose
My Github profile README intro. https://github.com/emjose

Here’s how I made the intro section for my Github Profile README.

The Name Banner

  1. I created a separate repo and made the name banner with tsParticles.
  2. I recorded a 9-second demo of the banner with GIPHY Capture.
  3. I resized the GIF to be under 10MB in size (see size limits).

The Introductory Text

  1. I wrote a bullet list about myself, and arranged them according to length (it tends to be visually appealing to the eye).
  2. I used simple color dot emojis in a rainbow arrangement.
  3. For links, I used <a href> </a> tags.

Chapter 6

README Headings
My section headings in Light and Dark Mode. https://github.com/emjose
My section headings in light and dark modes. https://github.com/emjose

For section headings, you can use Markdown or HTML syntax.

For my Github, I made custom headings in Adobe Photoshop because I wanted some styling for my profile, and I like thicker typefaces.

If you don’t have Photoshop, check out Canva in the next section!

Canva Method of Creating Custom Headings

Creating a project on Canva.com
Creating a project on https://www.canva.com/ See steps below.

Creating a Canva Project

  1. If you don’t already have Canva Pro, sign up for a free month trial.
  2. When logged in, press the purple “Create a design” button.
  3. Choose a design template, or press “Custom size.”
  4. If you press “Custom size,” make the width larger than 855 pixels.
Creating a heading with a transparent background on Canva.com
Making headings with transparent backgrounds on https://www.canva.com/ See steps below.

Making Headings (continued from previous section)

  1. In the new menu that appears on the left, select “Text.”
  2. Select “Add a heading” and drag it to the workspace on the right.
  3. Customize your heading’s content, size, color, and formatting.
  4. Press “add page” and repeat Steps 6 and 7 for every heading.
  5. When ready, press the download button on the upper right.
  6. Adjust size if needed. Check box for “Transparent background.”
  7. Ensure that the format is PNG, and press “download.”
  8. If you have multiple headings/pages, your Canva download will be in zip format, and each heading will be a separate file.

I highly recommend Canva! It’s excellent, and Canva Pro can also remove backgrounds for images that you upload. This is an extremely useful tool that I’ve used in various projects. When it comes to images, it’s easier to remove backgrounds in Canva than in Photoshop.

Chapter 7

README Badges
Static badges in my Github profile: https://github.com/emjose
Static badges for technologies in my Github profile: https://github.com/emjose

In READMEs, badges convey information in an at-a-glance format.

Badges can be static, or they can be dynamic by containing metadata with up-to-date metrics or status of a project or repository.

Badges make your READMEs and repos more polished and professional (I myself need to add them to my project repos — I’m working on it!)

Badges can come in a variety of styles (flat, plastic, for-the-badge, etc.), and it is easy to manipulate the endpoints for style, logos, dimensions, and color.

Badge styles on shields.io
Example of badge styles on https://shields.io/

Customizing Badges

In my Github profile README, I only have static badges so far, but here’s how I included them in my profile:

  1. I first sought out badges and styles on Shields.io.
  2. After some experimenting and googling, I came across this great markdown badge repo of the badges I needed.
  3. Simple Icons was instrumental for logo and color values.

In my Github profile, the blue Twitter badge..

The social media badges in my Github profile: https://github.com/emjose
Social media static badges in my Github profile: https://github.com/emjose

..looks like this in code:

<a href="https://twitter.com/Emmanuel_Labor"><img src="https://img.shields.io/badge/twitter-%231DA1F2.svg?&style=for-the-badge&logo=twitter&logoColor=white" height=30 width=100 alt="Twitter badge"></a>

1DA1F2 is the hexadecimal color value used by Twitter, and I’ve bolded the attributes for style, logo, logo color, height, and width.

A collection of brand logos and colors on simpleicons.org
https://simpleicons.org/ has an extensive and searchable collection of brand company logos and colors.
  • If you add height and width attributes for a badge, the logo text may stretch or squeeze depending on word length. I didn’t mind this effect since uniformity in badge size was more important to me.
  • Note: Some badges lose uniform size in the Github mobile site/app.
README badges in a mobile device.
Despite the uniform dimensions in a web browser, badges are not uniform in a mobile device.
The #100DaysOfCode section in my Github profile: https://github.com/emjose
The #100DaysOfCode section in my Github profile: https://github.com/emjose

Chapter 8

Github Stats

Dynamically rendering Github Stats are a great way to showcase your activity, contributions, and proficiency in languages, and implementing them is much easier than you think!

My Github stats generated by https://github.com/anuraghazra/github-readme-stats
My Github stats generated by https://github.com/anuraghazra/github-readme-stats

To Generate Your Stats

  1. Go to Anurag Hazra’s awesome Github README Stats repo.
  2. Change the ?username= values to your GitHub username.
[![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra)](https://github.com/anuraghazra/github-readme-stats)

The Github README Stats documentation has many options for customization in attributes, color, theme, and size.

  • For visual consistency, the gradient in my #100DaysOfCode section matches the gradient in my Github Stats section.
  • The left card has 4 background hex values and the right card has 3 background hex values to form the gradient.
  • I tweaked the width of the cards to be as equivalent as possible when the browser is resized (they stack atop each other when resized).
  • For some reason, I could only use even values for the card width.

Chapter 9

Project READMEs

I was happy with how my Github profile README turned out, but the work had only just begun.

I began writing READMEs for my projects, and they first looked like this:

The initial look of my READMEs.
The initial look of my READMEs. https://github.com/emjose

The initial READMEs were straightforward and technical, but I remembered the recruiter’s words about Github presence, and how it communicates who you are as a person and as a developer.

The project READMEs were decent, but they were lacking personality.

I realized that if my Github profile README represents me, then my project READMEs should do the same. They should be READMEs that I myself would want to read.

After some work, here’s the makeover I gave to my project READMEs:

One of my READMEs for #100DaysOfCode. https://github.com/emjose/one-hundred/#header
One of my READMEs for #100DaysOfCode. https://github.com/emjose/one-hundred/#header

Chapter 10

Project Headings

For brand consistency with my Github profile README, I created custom project README headings with Adobe Photoshop.

The process was nearly identical to the steps in the README Headings section, but this time, I increased the dimensions of the Photoshop document.

Alternative to Photoshop

Using a free month trial of Canva Pro is a great option for creating custom text headings with transparent backgrounds.

Currently, gradient text effects aren’t available yet on Canva, but they have an extensive menu of effects and options for size, color, and formatting.

Please see the Canva method of creating custom headings.

Text color choices on Canva.com
Headings can be customized on https://www.canva.com/

Chapter 11

Writing READMEs

Sylwia Vargas, one of my amazing instructors at Flatiron School, wrote an excellent blog on the Recipe for a good readme.

Sylwia wrote it best that good READMEs incorporate these points:

1. Write it well

2. Title, description and table of contents

3. Setup and stack

4. Know your audience

5. License

6. Contributions

7. Contributors

8. Next steps

Thank you Sylwia!

Licensing, Copyright, and Trademark

I’m still figuring out how to properly add licensing and open source information to my READMEs, but I am careful to acknowledge copyright and trademark of any intellectual property referenced by my projects.

Copyright example from one of my repos.
Copyright acknowledgement from my repo https://github.com/emjose/opening-crawl/#header

Do not forget to fill out your repo’s About section:

  • Short description
  • Website (if applicable)
  • Topics for improved search
  • Releases, packages, and environments
About section from one of my Github repos.
The About section from my repo https://github.com/emjose/opening-crawl/#header

Check out these README Resources!

Chapter 12

Show, Don’t Tell

It’s crucial to write well in READMEs, but text has its limits. Whenever possible, Show, don’t Tell.

This means including images, videos, badges, GIFs, icons, favicons, etc., that can demo and showcase your project better than words can. Most people are visual learners, and visuals enrich the experience of your READMEs.

My Github repo: https://github.com/emjose/form-validation/#header
Left: my repo before. Right: my repo after. Visual aids enrich the experience of your READMEs.

In Markdown, this is the format for images and GIFs:

![GitHub Logo](/images/logo.png)Format: ![Alt Text](url)

Alt Text (alternative text) is used to describe the appearance or function of an image. Providing alt text is a prime principle of web accessibility for the following reasons:

  • Visually impaired users may be using screen readers that read the alt attributes of website images.
  • If an image cannot be loaded, the alt text is displayed instead.
  • Descriptive alt text enhances search engine optimization.

Social Preview Image

In your repo’s settings, upload an image under “Social Preview” to enhance how your repo appears in social media platforms.

Social preview of my repo: https://github.com/emjose/block-animation/#header
In your repo’s settings, upload an image in “Social preview” to represent your repo.

Keyboard shortcuts for capturing screenshots on a Mac

  • shift-command-3: captures your entire screen
  • shift-command-4: drag the crosshairs to capture an area
  • shift-command-5: record your screen (edit in QuickTime or iMovie)

Recording GIFs

To remain under 50MB, I recommend recording GIFs with Screencastify for 15 seconds or less at an exported width of around 1000 pixels.

Favicons

Favicons are the small website logos/icons that appear in a web browser tab.

Favicons add brand identity to your websites, enhance SEO, and they aid in quickly identifying your website when many browser tabs are present.

My logo favicon. © Emmanuel Jose. All Rights Reserved.
Custom logo of my initials. © Emmanuel Jose. All Rights Reserved.
My logo favicon in the same of a spade.
My logo favicon. © Emmanuel Jose. All Rights Reserved.
  • Favicons should have square dimensions and be in PNG or ICO format.
  • Upload your favicon to an image or assets folder in VS Code.
  • The <link> element for your favicon should be placed under the <title> element in your index.html file.

<title> Website Title </title>
<link rel="icon" type="image/jpg" href="favicon_image_location"/>

Favicon Resources

Chapter 13

Navigation Header

While I was creating my #100DaysOfCode project READMEs, I found myself spending too much time trying to find the right project repo.

As useful as the main Github repository list is, I still had to type, search, and filter to find the repo. It was getting to be a nuisance, but it gave me the idea to create a navigation header to quickly navigate through related repos.

This is entirely optional, but read further if you’d like to see how I implemented the navigation header.

The navigation header in my repos: https://github.com/emjose/one-hundred/#header
The header that connects my #100DaysofCode projects. https://github.com/emjose/one-hundred/#header

Navigation Setup

My #100DaysOfCode Log: https://github.com/emjose/one-hundred/#header
The table in my #100DaysOfCode log: https://github.com/emjose/one-hundred/#header
  1. I recorded all of my #100DaysOfCode repo links in an Excel document.
  2. I made a new repository logging my projects in list form, based on Chandrika Deb’s excellent #100DaysOfCode Log.
  3. In Adobe Photoshop, I made custom PNG text images for “Day,” “Date,” “Project,” “#100DaysOfCode,” “Prev,” “Next,” and a name banner.
HTML and Markdown Table Syntax
I used the HTML Table syntax on the left in order to place navigation images side-by-side.

Placing Navigation Images Side-By-Side in Markdown

  1. I thought I could place the “Prev” and “Next” images side-by-side in Markdown by reducing their pixel widths, but this only stacks the images on top of each other.
  2. The workaround is to place images inside a Markdown table.
  3. I made a Markdown Table in the first project repo and adjusted the pixel widths of the navigation text so that they all looked uniform in size.
  4. Once the Markdown table appeared how I wanted, I applied the code across all project repos.
  5. Using the Excel document of repo links, I wrapped <a href></a> tags around the “prev” and “next” navigation images, and sequentially linked all the projects together.
  6. The “100DaysOfCode” image in the navigation header was linked to the main repo log of projects.

Here is the basic format of the navigation header:

Navigation Header of my repos. https://github.com/emjose
The navigation header for my #100DaysOfCode projects: https://github.com/emjose/one-hundred/#header
<table><tr><td> <a href="URL"><img src="path/image" alt="prev"/></a> </td><td> <a href="URL"><img src="path/image" alt="center"/></a> </td><td> <a href="URL"><img src="path/image" alt="next"/></a> </td></tr></table>

Chapter 14

Navigation Tips

How to make a “Back to Top” link:

<p id="header"><p>  
[the contents of the README]
<a href=#header>Back to Top</a>
  1. At the top of the README, anchor a <p> tag with id of “header”
  2. At the bottom of the README, wrap <a> tags around text that targets the #header id.
  3. If your “back to top” link is an image, the last line should be:
<a href=#header>![Back to Top](path/image)</a>

Basic Format of a Table of Contents in a README

Basic Format
- [alt text](#id-of-header)
____________________________________________________________________
# Table of Contents- [Heading 1](#heading-1)- [Heading 2](#heading-2)- [Heading 3](#heading-3)- [Heading 4](#heading-4)- [Heading 5](#heading-5)
# Heading-1
[content of section]
# Heading-2
[content of section]
# Heading-3
[content of section]
# Heading-4
[content of section]
# Heading-5
[content of section]

Github now generates a Table of Contents button at the top of READMEs, which you can enable or disable in the repo’s settings.

One more thing…

The End… is the Beginning

Thank you for reading this Github Makeover Story!

I’m proud of the steps I’ve taken to express my creativity and personality on Github, and I hope this can help you to do the same!

This is only the beginning of using Github to its fullest.

There’s so much more to learn and to improve upon and it’s the journey, not the “Happily Ever After,” that matters.

Emmanuel

GithubTwitterLinkedinInstagram

Back to Top

--

--