Creating a Killer GitHub Profile README
The computer science field is a little bit different than other industries when it comes to selling yourself. And I’m not saying that CS is “special” or a mystical unicorn of a job market. Much of what makes computer science just “a little bit different” is its expectation of independence. In other words, being an independent computer scientist (or more commonly titled “independent software developer”) is a more common expectation than being an independent accountant or an independent… doctor? It’s hard to find examples, mostly because in most other fields, becoming an independent “fill in the blank” is a goal that very few people achieve or even dream of; it’s a lofty goal that demands a high-ranking position. On the other hand, simply typing
print("Hello World")nets you the title of independent software developer on the spot. I jest, but there is also truth in this joke. “Independent software developer” doesn’t have a requirement of high accomplishment attached to it like a doctor might. A doctor who owns his/her own business has employees, a building or suite, their own equipment, years of schooling, high exam scores, decades of experience in the field, etc. At least, that’s the assumption. The assumption that comes with being an independent software developer is that you have a passion for programming. That’s it. And that assumption might not even be the case (video is timestamped):
The video above is from Fireship, one of my favorite tech/programming channels that has been popping into my feed more and more in the past few weeks. The main takeaway here is that it’s perfectly find to treat coding as nothing more than a job. Going down this “route” doesn’t mean you won’t reach your full potential, although it’s certainly easier to show your passion for programming by doing it in your free time.
This brings me to the main point of this article: The GitHub README. If you’re passionate about programming (to any extent, don’t fall victim to imposter syndrome here), then selling that passion to employers, friends, coworkers, or whomever ultimately manifests in the projects that you do. And what better way is there than to show them off in a killer GitHub README?
What is a README?
I’m assuming here that you are at least somewhat familiar with GitHub, and if you feel like you aren’t, then just do a quick search for “github,” do some reading, and most importantly, explore some repositories.
A GitHub README is a file written in Markdown, a text-to-HTML markup language most commonly used to create the aforementioned README file (titled “README.md”). You’ll find countless README files when exploring GitHub, most of which are created to give a brief guide or introduction to what a project is, like this one for the popular Old School RuneScape client, RuneLite. You can take a look at the code for that README by displaying the source blob (button shaped like “code” or HTML tags), but I’ll also include it along with its rendered blob below (the first one is a .txt file because Github Gist renders .md files into rendered blobs automatically):
If you do a quick skim of the code, you’ll realize that it’s not that bad. Then again, reading markup languages can only get so complicated; they simply structure elements such as text and images after all. And this simple code produces this minimalistic and clear README:
I would write a quick guide to Markdown, but it would be pretty redundant considering how many great cheat sheets/guides already exist. Instead, I’ll provide a couple of guides and a few tips on my experience as a beginner with Markdown.
Use this cheat sheet for general syntax of Markdown and this longer, more in-depth guide for a better understanding of the intricacies of Markdown. It’s better to learn something by actually doing it, so I would mess around with Markdown in one of two ways. Either (a) create a README.md file for a project repository on GitHub and alternate between the source code and the rendered blob (between “edit file” and “preview” tabs) or (b) use a VSCode extension for previewing Markdown. It’s even better to learn something by teaching it, so it’s not a terrible idea to create a guide to Markdown in Markdown as your first project.
Markdown is fairly simple, however, so I would recommend skipping this meta project and just make a README for a project that you’re passionate about. The best part is, the project doesn’t even have to be done or in development! Use this as an opportunity to plan out what you envision for the project. If you have no idea where to start on ideas for a project, then just ask yourself these questions: What is a problem that I encounter/have encountered? How can it be fixed? How can that solution be implemented through code? The first question can be answered just by thinking — take the word “problem” liberally, as it can be something minor or just the fact that something cool that you have in mind doesn’t exist yet! The second question of “How can it be fixed?” should get you thinking about the general project structure and how it effectively solves or remedies the “problem” in question. The last question is where almost all of your time will be sunk into, as you’ll need to do research on how you’re going to build this project. What language(s) will you use? What will the project directory look like? How will you deploy it? As an app? A website? A command-line application? Even more time will be required to actually write the code for the project, but as mentioned earlier, that doesn’t necessarily have to be a concern for its README. Of course, any README is further refined by a project being developed or completed as you gain a deeper understanding of what you’ve built, its limits, and how bugs/issues you encountered and fixed elucidate the project’s potentials (and your own potentials 😉).
The Profile README: A Comprehensive Guide
As great as READMEs for projects can be, the main focus of this article is on the profile README. In the computer science world, your GitHub profile is something of a LinkedIn page. Although it lacks the “connection” feature that LinkedIn so heavily emphasizes, GitHub is still the primary platform for viewing projects of programmers; there is a reason why so many job/internship applications request a link to your GitHub. Beyond the practical purposes of finding employment opportunities, GitHub profiles are projects of their own — I’m incredibly passionate about my own GitHub profile and love that I’m able to track my progress through something that I’ve created. What follows is a comprehensive guide on how I created my GitHub profile, though I certainly recommend deviating from the following “template” and producing your own unique README, even if it takes inspiration from many sources. After all, what is a software developer but a proficient Googler? Once again, I’ll include Gists for the source code and the rendered blob, respectively, but I’d recommend visiting my profile directly to view it in your browser as well.
We’ll discuss those spooky HTML tags very soon. Here’s the rendered blob, which was created to match the dark theme of GitHub and looks better when viewed in a full-screen browser window:
Let’s first go through a list of steps that you can follow to produce an aesthetically pleasing README. After these steps, I’ll get into the specifics of my own profile, which may prove to be particularly useful if you’re wondering where those images, gifs, stat card, and all the fancy stuff is implemented. My own GitHub README didn’t follow these exact steps, so once again, get creative and feel free to do whatever you think feels right!
Step 0: Setup
Before you can create a README that will appear on your profile, you have to create a repository with the same title as your GitHub username. For example, since my GitHub username is “kevinfengcs88,” the repository that I need to create will have the same name, leading to an overall directory of “kevinfengcs88/kevinfengcs88.” You’ll notice that this repository is special, and GitHub even provides a persistent note about this:
All there’s left to do is to create a README.md in this repository, and any changes you make there will appear on your profile!
Step 1: The Basics
There’s no reason to start off by including all the fancy features. It’s the same with creating a website — why refine all of the CSS styling right at the start? Getting the basic HTML skeleton down first is your priority with a website. To apply that here, you’ll want to begin with a simple title that greets the visitor of your README and introduces yourself. Something as simple as “Hello my name is ___________” should suffice. Remember to include a ‘#’ to make the text an H1 header.
# Hi there, I’m Tobey Maguire!After that you’ll want to add some bullet points about yourself. Include some of your hobbies, your current status with school/employment, and maybe a short blurb about what you’re currently learning. It’s also a good idea to include some links on how people can contact you. Include your email, LinkedIn, personal website, etc.
How to reach me: <a href=”mailto:kevinfeng.cs88@gmail.com”>kevinfeng.cs88@gmail.com</a>Step 2: Images, Gifs, and Shields
Now it’s time to add some visual elements to enhance your README. If you want to include some programming languages, consider adding your “tech stack.” Not only is including your tech stack useful for viewers of your README to gain a better understanding of what tools you’ve worked with, but it also looks pretty cool. By “tech stack,” I mean whatever operating systems, programming languages, IDEs, etc. that you work with. The easiest way to find images to use is from other GitHub profile READMEs, so go ahead and copy the links from my README if you so desire. Otherwise, if you can find high quality images from online, you can include HTML image tags that specify the “src” attribute as the link to that image’s address. It’s also pretty common to see gifs on GitHub profiles. It can be anything, from a large pixel art gif of a character working at his computer to a small gif of a hand that waves.
Shields.io is one of the most useful resources for creating a polished GitHub README. A shield is essentially a badge that can display a few pieces of information. It can be as simple as a logo or as complex as a badge representation of a product/piece of hardware that you use. I’m going to get a bit more in-depth on shields in the section following these steps, but if you get confused on the “syntax” of shields, I’d recommend taking a look at this GitHub repository from Alexandre Sanlim. As for integrating your shield into your README, you can either go with the Markdown method which looks like this:
[](https://kevinfeng.ga/)Or you can insert an HTML image tag like mentioned before:
<img width=50px src=”https://cdn.freebiesupply.com/logos/large/2x/eclipse-11-logo-png-transparent.png">Don’t forget that you can use these visual elements to enhance what you’ve created in the first step! And I almost forgot — emojis are a great addition to READMEs as well.
Step 3: Fancy Stuff
The fancy stuff also happens to be the fun stuff. I had a great time adding modules to my README that made it stand out more and look more refined. I have three main recommendations here.
First up are GitHub stats. GitHub stats are a great way to show off what you’ve done so far on GitHub and what languages you’re most familiar with. I’d highly recommend using this repository from Anurag Hazra. The README of this project includes everything you’ll need to generate your own GitHub stats and includes very in-depth documentation, including how to exclude specific repositories from your “Most Used Languages” or how to hide certain statistics. There are also a ton of customization options; I advise you to give those some exploration as well.
Next up are custom pins, which can also be found on the same repository from Anurag. Normally, GitHub only allows you to pin up to 6 repositories, but with these custom pins you can “bypass” that limit. Just like the GitHub stats, you’ll find everything you need in the incredible documentation that Anurag has provided on his repo.
Lastly, for my fellow bloggers, is to include your latest blog posts on your GitHub README. Sounds cool, right? At the same time, it can be a very onerous and repetitive task to continuously commit some changes to your README file every time that you post a new article on your blog. Fortunately, we have access to GitHub Actions, which can help you automate mundane tasks like updating your most recent blog posts. Consider this repository that automates a blog post workflow from Gautam Krishna. Implementing it will ensure that your README has all your latest blog posts every hour, on the hour. Like Anurag, Gautam has very clear and in-depth documentation on his repository, so as long as you follow the steps that he’s written up, you should be good to go.
If you also blog on Medium, then you might run into some issues with the workflow failing. Don’t worry, this is completely normal (my workflow has failed a few times within the past 48 hours). If you find that your workflow is consistently failing every hour, then Medium might have some issues on their end. One potential workaround is to create an RSS mix, which I resorted to when I first encountered this problem. You can find the details in this GitHub issue.
My README’s Specifics:
In this section I’ll go over how to take full advantage of shields and provide a quick rundown on my own profile. Let’s start with designing a cool badge with Shields.io:
I’m a huge fan of AMD (I’ve built an all AMD gaming PC), so let’s design an AMD Ryzen badge for their 3700X processor. After navigating to the homepage of Shields.io, scroll down until you see this:
We’re actually going to include an AMD logo on this shield, so there’s no need to include the text “AMD” on this. So let’s just fill in the inputs accordingly:
You’ll see that after clicking on “Make Badge” that a new tab opens in your browser with a pretty pathetic looking badge that clearly doesn’t even have the correct shade of AMD’s red (following images are on 500% browser zoom).
We’re going to fix this by altering the text in the address bar. Let’s go back to the original tab, scroll a bit further until you see the styles.
I prefer the for-the-badge style, so let’s copy the text there and paste it to the end of the address of the tab with our current (pathetic) badge.
This is certainly looking better in terms of style, but we need to get rid of that AppVeyor logo and change the color to a shade of red that’s not as rusty.
And that’s it! We’re done. By changing the color “red” to the actual hex color code of AMD red (ED1C24) and changing the logo to AMD, we’ve created a pretty neat looking badge. If you’re wondering what other logos you can use and their exact hex color codes, take a look at Simple Icons. If you’re concerned with how small the AMD logo is in this badge (it looks pretty blurry on only 100% zoom), this can be remedied by increasing the size of the badge in your README. I achieved this through using the aforementioned HTML trick by including image tags and setting the “height” attribute to 40.
Don’t forget to make your shields clickable links when applicable (I might add links to my PC component shields after I’m done with this blog post now that I bring that up!).
Now for the quick rundown on my GitHub profile:
Intro, Stats, and Repos:
For the first section of my profile, I’ve included a simple typing SVG (the text is gray to accommodate for both light and dark GitHub themes), which you can customize and include in your README at this repository, some links, including my Medium blog and LinkedIn, and instead of Markdown bullets, emojis (everyone seems to do this, I won’t argue against it). I was able to get my GitHub stats card positioned on the same horizontal plane as my languages card by putting them in a Markdown table and removing the borders of both cards. Otherwise, they act like HTML divs, occupying new lines as block elements. Not much to say about the custom repo pins; I decided to include 8 because I could have just used the built-in GitHub pins with any even number of repositories less than 8.
Images and Shields Galore:
The next section contains a lot of images and a lot of shields. For the “Languages and Tools” section of my profile, I never ended up finding a single GitHub repository with all the icons that I needed (although I’m sure that it exists), so I ended up using a lot of image addresses from Wikipedia. I would search up something like “C programming language logo,” find a reasonable image, and use the image address as the “src” attribute’s value. I was inspired to create shields to represent my custom PC build from Alexandre Sanlim’s profile, and I’m proud to say that it to be pretty epic. As mentioned earlier, I created my shields just by generating basic shields, altering the address bar’s values until I got what I wanted. Simple Icons is such a great resource for coloring your shields accurately.
Dynamic Blog Posts:
The section on my profile of updated blog posts is fairly simple; I struggled much more with the functionality of the workflow rather than the Markdown itself. If you find that your blog post workflow fails to run, just mix your current blog feed with a dummy one, using a tool like RSS Mix. Here’s an example of a dummy feed that you could use:
https://raw.githubusercontent.com/gkr-bot/empty-feed/main/empty.xmlPinned Repositories:
You didn’t think that the GitHub profile was all README did you? Well, it’s certainly almost all README, but you can still include pinned repositories with GitHub’s built-in function, especially if you didn’t utilize custom pinned repos. I found it fitting to only pin one repository: My personal repository containing the README just above it! Pretty meta.
README Generators:
I’m not going to sit here and pretend that writing Markdown is all that fun. Writing Markdown for the purposes of making your GitHub profile cool is certainly fun, but the writing of Markdown can be dull at times. Just compare it to HTML. Both HTML and Markdown are markup languages, and we all know how boring writing raw HTML from scratch can be.
Enter the README generator, a seemingly simple and fast way to generate a README for your GitHub profile. Actually it’s not “seemingly simple and fast,” it just is simple and fast. Just one example of these tools is the GitHub Profile README Generator by Rahul Jain. It provides a straightforward layout, with a list of languages, APIs, and packages to choose to show off your skills. There’s also a long list of socials that you can plug, and some add-ons, like the GitHub stats from Anurag, and some GitHub Actions features that can dynamically update your most recent blog posts (although I don’t see how this works since it only generates a Markdown file for you).
There are drawbacks to using generators like these, however, as they may restrict you from creating exactly what you want. To demonstrate this, I’ve generated a dummy README profile that looks, frankly, pretty unpolished:
Just a short list of what I might change for this README:
- Alter shields (the profile view is just one example) to look more refined
- Make link texts “normal” text, not the actual addresses themselves
- Find more consistent logos for tech stack (some have tiny, unreadable text)
- Set GitHub stats and languages card to be next to each other horizontally
As implied above, if you’re using a README generator, I would highly recommend getting into the Markdown code yourself to change it to your liking. The generator only gives you so much freedom on its own, after all. But once again, feel free to do whatever you want with your README; if the generated output is exactly what you want, then leave it alone.
Lastly, I just wanted to give credit where credit is due. I only started creating my GitHub README when a certain video popped into my YouTube recommended:
This video from codeSTACKr is incredible, providing a very straightforward explanation on much of what I outlined in this blog post. Most importantly, he explains how to manually start the blog post workflow that Gautam created — particularly useful when your workflow fails and you want to manually restart the cycle to see its behavior.
Don’t forget the duality of your GitHub profile: It’s both a resume and a fun project that grows alongside you—keep it professional and fun at the same time, and you’re sure to have a blast with it. Good luck!
