README a Makeover Story

How to Create and Customize Your Github READMEs

Banner for my Github Profile:


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

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

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

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

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.

On VS Code, right-click on the file to preview edits. READMEs cannot use stylesheet files.

Chapter 4

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

Here are excellent and extensive Markdown syntax resources:

Chapter 5

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

My section headings in light and dark modes.

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.

The following steps are optional, but read further if you’d like to create custom headings too!

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.

You can create a Photoshop document with a much larger canvas size to type out all the section headings in one text layer — BUT you will then have to crop each individual heading when you export, and this is cumbersome.

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

Canva Method of Creating Custom Headings

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

Static badges for technologies in my Github profile:

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.

Example of badge styles on

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

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>

1DA1F2 is the hexadecimal color value used by Twitter, and I’ve bolded the attributes for style, logo, logo color, height, and width. 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.
Despite the uniform dimensions in a web browser, badges are not uniform in a mobile device.
The #100DaysOfCode section in my Github profile:

Chapter 8

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

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

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

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

Chapter 10

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 to 2800 pixels in width and 280 pixels in height.

Then, I increased the size of the text layers relative to the canvas width to make them appear even larger when exported.

I also applied a gradient overlay to the headings to give the project READMEs a much needed dose of color. To do this, right-click on a text layer and select “Blending Options.”

In Photoshop, right-click on a text layer and select “Blending Options.”

Then, select “Gradient Overlay” and adjust colors and gradient direction.

Photoshop’s gradient overlays feature many options for customization.

I exported each text heading in PNG format with a transparent background, and then uploaded them to the README’s Assets folder in VS Code.

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.

Headings can be customized on

Chapter 11

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 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
The About section from my repo

Check out these README Resources!

Chapter 12

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.

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.

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

Custom logo of my initials. © Emmanuel Jose. All Rights Reserved.
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

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 header that connects my #100DaysofCode projects.

Navigation Setup

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

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

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…

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.



Back to Top

Artist turned Coder. Dog Dad. 🏳️‍🌈

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