README a Makeover Story
How to Create and Customize Your Github READMEs
- Introduction: Once Upon a Time
- Chapter 1: Let’s do a Makeover!
- Chapter 2: Design + Inspiration
- Chapter 3: README Setup
- Chapter 4: README Formatting
- Chapter 5: README Content
- Chapter 6: README Headings
- Chapter 7: README Badges
- Chapter 8: Github Stats
- Chapter 9: Project READMEs
- Chapter 10: Project Headings
- Chapter 11: Writing READMEs
- Chapter 12: Show, Don’t Tell
- Chapter 13: Navigation Header
- Chapter 14: Navigation Tips
- One more thing: The End… is the Beginning
Introduction
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!
My Github after the 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:
- Adam Alston’s Github — the particle banner and gradients! ❤️
- Ava’s Github — the aurora banner and clean bulleted list! ❤️
- Thomas Guibert’s Github — the colorful tech badges! ❤️
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!
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.
- 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.
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:
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.
Here’s how I made the intro section for my Github Profile README.
The Name Banner
- I created a separate repo and made the name banner with tsParticles.
- I recorded a 9-second demo of the banner with GIPHY Capture.
- I resized the GIF to be under 10MB in size (see size limits).
- Size limit of profile README GIFs: 10MB.
- Size limit of project README GIFs: 50MB.
- How to add GIFs to your Github README
- Demo your App in your Github README with an Animated GIF
- Screencastify is another excellent screen recorder that can export GIFs.
The Introductory Text
- I wrote a bullet list about myself, and arranged them according to length (it tends to be visually appealing to the eye).
- I used simple color dot emojis in a rainbow arrangement.
- For links, I used <a href> </a> tags.
- Emoji Cheat Sheet 1
- Emoji Cheat Sheet 2
- In VS Code, access emojis by pressing and holding the following keys: control-command-space
Chapter 6
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 Canva Project
- If you don’t already have Canva Pro, sign up for a free month trial.
- When logged in, press the purple “Create a design” button.
- Choose a design template, or press “Custom size.”
- If you press “Custom size,” make the width larger than 855 pixels.
Making Headings (continued from previous section)
- In the new menu that appears on the left, select “Text.”
- Select “Add a heading” and drag it to the workspace on the right.
- Customize your heading’s content, size, color, and formatting.
- Press “add page” and repeat Steps 6 and 7 for every heading.
- When ready, press the download button on the upper right.
- Adjust size if needed. Check box for “Transparent background.”
- Ensure that the format is PNG, and press “download.”
- 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
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.
Customizing Badges
In my Github profile README, I only have static badges so far, but here’s how I included them in my profile:
- I first sought out badges and styles on Shields.io.
- After some experimenting and googling, I came across this great markdown badge repo of the badges I needed.
- Simple Icons was instrumental for logo and color values.
In my Github profile, the blue Twitter badge..
..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.
- 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.
- I did take liberties in adjusting color values to create an aesthetically pleasing effect, or to create a gradient effect.
- For the #100DaysOfCode section, I looked up gradient wallpapers and identified the hex color values with Image Color Picker.
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!
To Generate Your Stats
- Go to Anurag Hazra’s awesome Github README Stats repo.
- Change the
?username=values to your GitHub username.
[](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
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 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:
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.
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.
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:
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.
Do not forget to fill out your repo’s About section:
- Short description
- Website (if applicable)
- Topics for improved search
- Releases, packages, and environments
Check out these README Resources!
- Make a README by Danny Guo
- A curated collection of Awesome READMEs.
- Comprehensive List of README Resources and Tools
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.
In Markdown, this is the format for images and GIFs:
Format: 
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.
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
- GIPHY Capture
- Screencastify automatically saves to Google Drive
- GIFs in Github READMEs cannot exceed 50MB in size.
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.
- 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.
Navigation Setup
- I recorded all of my #100DaysOfCode repo links in an Excel document.
- I made a new repository logging my projects in list form, based on Chandrika Deb’s excellent #100DaysOfCode Log.
- In Adobe Photoshop, I made custom PNG text images for “Day,” “Date,” “Project,” “#100DaysOfCode,” “Prev,” “Next,” and a name banner.
Placing Navigation Images Side-By-Side in Markdown
- 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.
- The workaround is to place images inside a Markdown table.
- 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.
- Once the Markdown table appeared how I wanted, I applied the code across all project repos.
- 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.
- 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:
<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>
- At the top of the README, anchor a <p> tag with id of “header”
- At the bottom of the README, wrap <a> tags around text that targets the #header id.
- If your “back to top” link is an image, the last line should be:
<a href=#header></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.
Emmanuel
Github • Twitter • Linkedin• Instagram
