Stand out on GitHub with a README profile

Recently GitHub released a new feature allowing users to show a custom README on their profile page. This is what GitHub has been missing in community building and user exposure: to customise your profile a bit to show who you are, what you can do, and why you are awesome.

There are some limitations though. As you may be aware GitHub READMEs only allow Markdown and some basic HTML. This hasn’t stopped people from trying to do something creative with it.

I took a look around how people have made awesome stuff, and decided to combine a few of them. Then I took it a step further, and made a self-updating README and configurable templates to enable everyone to benefit from it. Now before I get into what I did, let me show you what my GitHub profile looks like at the moment of writing this article.

My GitHub profile as of writing

So first you see a little bit about myself, badges to show what I work with, then my latest articles which are pulled from the Medium RSS feed, some GitHub stats, and where to find me. Like I mentioned earlier, this README updates itself every day. Meaning that when I post a new article on Medium, it will be added in the list automatically using GitHub Actions.

I use Pug to render templates and inject variables wherever necessary. By doing this I can also split my sections into different templates. The main set up is inspired by Thomas Guibert’s repository. I just felt that this implementation could and should be more open source focussed and more re-usable for others.

Let’s get started and create you a GitHub profile with what I have created! The steps are easy! Not interested in doing exactly what I did? Then you can at least use my repository as reference.

1. Create a new repository 🗄️

Create a new repository on GitHub and use your username as the name for the repository. If you enable the Initialize this repostory with a README checkbox, you would already see something on your profile immediately.

 

2. Pull from my repo 🚃

Create a folder on your computer and use the following commands to set up your git properly:

// Initialise your folder with your repository
git init
git remote add origin git@github.com:<your-username>/<your-username>.git

// Add my repo as upstream and pull
git remote add upstream git@github.com:arjenbrandenburgh/arjenbrandenburgh.git
git pull upstream master

Now you have a copy of my repository in yours. Look around a bit! The important parts are the config.ts and the templates folder. But we’ll get to that in a bit.

3. Change the configuration ⚙️

Open up config.ts and have a look around. There are several sections there.

You can change the badges you want to show in the “social” part on where people can find you. I am using four, but also added two which are commented out for myself.

Then you have some GitHub configuration. Put your username in, you can adjust the colors for the “GitHub stats”, select which stats you want to show, and which repositories you wish to highlight

You can enable the Instagram module. When enabled it will find your latest Instagram posts by using Puppeteer.

The Medium-articles section defines whether you want to show your latest Medium articles. It will use the Medium RSS feed for a user and get the latest ones.

Last you can show a list of badges with what you can work with. The logo is usually selected by the name, but sometimes you want to use a different logo. You can find all available logos at https://simpleicons.org/.

4. Change the templates 📝

Look in the templates folder and see what’s there. You will definitely want to change the about-me.pug file, since it contains information about me. The rest you can change to your liking.

Also take a look at main.pug in the root. Maybe you want to change the title or switch around the order of the templates.

5. Push it! 🚀

Time to push the code! You can see how it turns out first though by using npm run build (don’t forget to npm install first!). It will generate the README.md file. So have a look, check if you are satisfied, and adjust the config and templates some more until you are ready! When you are, we will push it to your repo.

git add .
git commit -m "Changed everything to my own needs"
git push origin master

The GitHub Actions should immediately trigger, and will take a few minutes to render. Now take a look at your GitHub profile! It’s gorgeous!

I really enjoy creating this to be as easy to use for everyone. In the spirit of open source you can open a pull request to add more sections that people can configure and add.

If you’re looking for ideas then have a look at the repository below, which lists a bunch of awesome people who have creatively used the README as well!

Hope this helps you out, and inspired you to do something awesome with your GitHub profile as well.

Who am I?

I’m a senior fullstack engineer and consultant working as Team Lead for Techspire in the Netherlands 🇳🇱. I have been working in software engineering for almost 10 years and still loving it every single day. My main expertise lies with Angular. As a true geek I love to expand my knowledge and am proficient with, amongst others, Python, Ruby on Rails and AWS.