README a Makeover Story

Particle Banner for my Github Profile:
Banner for my Github Profile:
Table of Contents


Once Upon a Time..

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

Chapter 1

Let’s do a Makeover!

“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.”

I’d give my Github a makeover!

Chapter 2

Design and Inspiration

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


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 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
  • Why? Because you will create the 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.
Open Preview option in VS Code.
On VS Code, right-click on the file to preview edits. READMEs cannot use stylesheet files.

Chapter 4

README Formatting
Comparison of Markdown and HTML.
Comparison of Markdown and HTML Syntax.

Here are excellent and extensive Markdown syntax resources:

Chapter 5

README Content

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:

Ask for feedback on your profile README before you publish.

My Github profile intro.
My Github profile README intro.

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.
My section headings in light and dark modes.

The Custom Headings

  1. In Adobe Photoshop, I created a new document that was 1555 pixels in width and 100 pixels in height.
  2. The dimensions can be anything, as long as they are wider than 855 pixels. 855 pixels is the max width of images rendered in a Github profile README (at least in normal browser settings on a MacBook laptop). Larger images will look sharper when resized on Github.
  3. I made a white background layer, a black background layer, and a transparent background layer, to test out light and dark modes.
  4. I created a text layer. It was left-justified and anti-aliasing set to “sharp.”
  5. I tested different bold typefaces, and I chose the Inter typeface (similar fonts are Helvetica Bold, Futura Bold, Archivo Black).
  6. For the typeface color, I chose a light gray hue that would be visible in both light and dark modes on Github.
  7. After choosing the color, I duplicated the text layer. For each copy, I typed a different heading, and all headings were the same point size.
  8. I disabled the visibility of the white and black background layers.
  9. I enabled the visibility of the transparent background layer.
  10. One by one, I enabled the visibility of each text layer, and individually exported each in PNG format with the transparent background.
  11. With the method above, each text heading will have the same canvas width, making them consistent and responsive on Github. The PNG format is best for maintaining image quality for resizing. The transparent background makes it easy to overlay text on various backgrounds.

Canva Method of Creating Custom Headings

Creating a project on
Creating a project on See steps below.
  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
Making headings with transparent backgrounds on See steps below.
  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.

Chapter 7

Static badges in my Github profile:
Static badges for technologies in my Github profile:
Badge styles on
Example of badge styles on

Customizing Badges

  1. I first sought out badges and styles on
  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:
Social media static badges in my Github profile:

..looks like this in code:

<a href=""><img src="" height=30 width=100 alt="Twitter badge"></a>
A collection of brand logos and colors on 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:
The #100DaysOfCode section in my Github profile:

Chapter 8

Github Stats
My Github stats generated by
My Github stats generated by

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](](
  • 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
The initial look of my READMEs.
The initial look of my READMEs.
One of my READMEs for #100DaysOfCode.
One of my READMEs for #100DaysOfCode.

Chapter 10

Project Headings
Photoshop Blending Options
In Photoshop, right-click on a text layer and select “Blending Options.”
Photoshop Gradient Overlay
Photoshop’s gradient overlays feature many options for customization.

Alternative to Photoshop

Text color choices on
Headings can be customized on

Chapter 11

Writing READMEs

Licensing, Copyright, and Trademark

Copyright example from one of my repos.
Copyright acknowledgement from my repo

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

Check out these README Resources!

Chapter 12

Show, Don’t Tell
My Github repo:
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)
  • 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

Social preview of my repo:
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


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
The navigation header in my repos:
The header that connects my #100DaysofCode projects.

Navigation Setup

My #100DaysOfCode Log:
The table in my #100DaysOfCode log:
  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.
The navigation header for my #100DaysOfCode projects:
<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]

One more thing…

The End… is the Beginning

Back to Top



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store