#2 路 Add a README to your GitHub profile

Add more substance to your GitHub profile with just a few steps

Dear reader,

I was today years old when I discovered that you can add a full README to your GitHub profile. I鈥檓 not referring to a README on a GitHub repository, I鈥檓 referring to a README on your GitHub profile.

Figure 1

It鈥檚 easy to add this README. Here are the details.

First step: create a new repository

GitHub will use the README of the repository that has the same name as your GitHub profile. My GitHub profile is simardcasanova so I needed to create a repository also named simardcasanova.

GitHub - simardcasanova/simardcasanova: README.md for my profile
README.md for my profile. Contribute to simardcasanova/simardcasanova development by creating an account on GitHub.

When you create the new repository, be aware of the three following settings.

Figure 2
  1. GitHub tells you that you鈥檙e about to create a special repository. The blue alert is a confirmation that you gave the right name to your repository.
  2. To make the README appears in your profile, you need to make the repository public. It鈥檚 possible to make it private as well, for instance if you want to first design your README behind closed doors.
  3. Don鈥檛 forget to check the box to add a README file. You can still create one later but it鈥檚 easier if the file is already created.

Once everything is in order, you can proceed and create the repository.

Second step: edit the README file

Navigate to your new repository. The blue alert (1) confirms it鈥檚 indeed a special repository.

Figure 3

To make the repository a bit more professional, you can add some metadata (4). To do so, click the cog icon (5) and adjust the details.

Figure 4

I haven鈥檛 dive into this yet, but I guess Topics could be an interesting way to enhance the discoverability of your profile in your area of expertise.

Now you probably want to edit the README itself. As shown in Figure 3, you can either click on the 鈥淓dit README鈥 button (1) or on the pen icon (3). GitHub opens an editor.

Figure 5

You need to use Markdown to style your README. If you鈥檙e not familiar with Markdown, here is a help page on GitHub Docs.

Basic writing and formatting syntax - GitHub Docs
Create sophisticated formatting for your prose and code on GitHub with simple syntax.

Last but not least, you can edit the README file directly from your profile.

Figure 6

Every time you want to update your profile, you just need to edit the README file. That鈥檚 it!

Third step: write a good README

As I just discovered this feature, I haven鈥檛 had enough time (yet) to see how people use it and what a good profile README looks like.

What鈥檚 sure though is that you can leverage the full set of features available in GitHub README files. You can display images and buttons 鈥 and probably many other things.

Extra step: choose which repositories to display in your profile

Thanks to pinned repositories (1), you can also choose which repositories people will see on your profile. It鈥檚 useful if you want to showcase a few specific repositories, for instance your most popular ones or the new cool thing you鈥檙e working on 鈥 such as LearnRstats 馃憖

Figure 7

Every time you want to update your profile, you just need to edit the README file. That鈥檚 it!

Third step: write a good README

As I just discovered this feature, I haven鈥檛 had enough time (yet) to see how people use it and what a good profile README looks like.

What鈥檚 sure though is that you can leverage the full set of features available in GitHub README files. You can display images and buttons 鈥 and probably many other things.

Extra step: choose which repositories to display in your profile

Thanks to pinned repositories (1), you can also choose which repositories people will see on your profile. It鈥檚 useful if you want to showcase a few specific repositories, for instance your most popular ones or the new cool thing you鈥檙e working on 鈥 such as LearnRstats 馃憖

Olivier