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
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.
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!
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?
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.
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:
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
- 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.
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
- In Adobe Photoshop, I created a new document that was 1555 pixels in width and 100 pixels in height.
- 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.
- I made a white background layer, a black background layer, and a transparent background layer, to test out light and dark modes.
- I created a text layer. It was left-justified and anti-aliasing set to “sharp.”
- I tested different bold typefaces, and I chose the Inter typeface (similar fonts are Helvetica Bold, Futura Bold, Archivo Black).
- For the typeface color, I chose a light gray hue that would be visible in both light and dark modes on Github.
- 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.
- I disabled the visibility of the white and black background layers.
- I enabled the visibility of the transparent background layer.
- One by one, I enabled the visibility of each text layer, and individually exported each in PNG format with the transparent background.
- 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 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.
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.
In my Github profile README, I only have static badges so far, but here’s how I included them in my profile:
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.
Check Out These Great Badge Resources!
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.
[![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.
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:
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.”
Then, select “Gradient Overlay” and adjust colors and gradient direction.
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.
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!
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:
![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.
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)
- 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 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"/>
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.
- 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>
How to make a “Back to Top” link:
[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>![Back to Top](path/image)</a>
Basic Format of a Table of Contents in a README
- [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)
[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.