If GitHub is a well-known tool among developers, some of its features are less known. For example, the theme of this article: the creation of a portfolio to display on your profile page using the README of a GitHub repository – this file typically serves to describe the project and explain its use to those visiting the page.
A portfolio in a GitHub README?
Yes, it might seem surprising at first, but it is indeed the case.
Since mid-2020, GitHub allows you to customize your profile page to display the information you want, using a simple README.md file.
What for?
More than just a simple gadget, this feature allows you to fully customize your profile and display much more information; making it a real portfolio, a mini CV.
And this has several advantages.
Standing out
As we know, competition among developers, especially freelancers, can be fierce.
For a job, project, a contract, a mission, there are often several developers who have all the necessary technical skills. The difference is then made on other aspects: the human side, availability, or the review of portfolio elements.
And using your GitHub profile as a portfolio is original and interesting; especially when you are still a junior.
It can show a recruiter or a CTO who is hesitating what you are capable of doing with little. It also shows that you are involved and take the time to do original things on your own time.
Replacing a website
Many developers have a site in their name. It is very useful for introducing themselves, presenting their skills and the projects they have worked on, in a much more personalized way than if they had only used LinkedIn or Malt.
Moreover, it also allows them to show directly what they can do, via the code, the UX and the UI of said site, which is very interesting if they are front-end developers, for example.
But using your GitHub profile instead of a site has several advantages; for example, it is much easier and can save a lot of time.
Before explaining how to create an attractive portfolio via GitHub, here is an example, so you understand well: https://github.com/CyrisXD/CyrisXD.
This is what is displayed on his profile page. Although I personally find it too cluttered, you can see what is possible to do: put a header, links, lists and statistics. You can even do more, as we will see later.
How does it work?
Now that we've seen the interest in creating a portfolio on GitHub, let's see how to do it.
Well, actually, it's very simple! As explained in the official documentation, you just need to create a GitHub repository that has the same name as your GitHub username, adding a README.md. When creating this repo, the following message will appear:
Once that's done, go to your profile page and... tada! A new element appears: the content of the README you just created.
All that remains is to modify it as you wish in the same way as any README file, by adding everything you want and saving the changes; they will be automatically updated on your profile.
The Markdown
I take this opportunity to make a small digression on how the README is written. As a developer, you have probably already had to modify this file, which is located at the root of most Git projects.
But if this is not the case or if you have not had the chance to do it often, know that the content of this type of file is written in the Markdown language (hence the .md extension).
If you are a developer, there is a chance that you know GitHub Actions. If not, to keep it simple, let's say that it is a tool provided by GitHub, allowing to do, among other things, continuous integration. Typically, it is used to execute a list of actions during a commit or a PR.
The interest here, without going into technical details, is that you can set up a Cron via GitHub Actions to perform tasks regularly that will indirectly update your README.md. For example, this allows you to retrieve and display information in real time (more or less), like counters, or a list retrieved via a stream, etc.
We will see an example of this use later in the article.
So, it's very easy to create a portfolio via the README of a GitHub repo. The problem is that it's a double-edged sword (exactly like a professional site): it can serve you as well as disservice you...
Therefore, it is advisable to follow a few tips to boost your chances of finding a permanent contract or a mission:
Keep your repo private during development
The same is true when we talk about any development project. When you are a developer and want to show code on GitHub (or GitLab or other), it is better to make sure everything is clean.
However, not only will everything be visible on your profile page, but the code of your README will also be visible to everyone...
So tip number 1: keep your repository private while you develop your portfolio. Once it's finished; switch it back to public.
Be creative
It's especially important if you are a front-end developer.
More and more developers are using and will use this GitHub feature, so you need to stand out from the crowd, otherwise it will not have served much purpose.
So you will need to step away from the tech side and be a little creative.
Markdown allows you to add, among other things, links, images, gifs, etc., which opens up more possibilities than simple text lists.
Here is, for example, this user, who had the idea to include an interactive tic-tac-toe game on his profile. The game uses GitHub Actions, which I explained earlier in the article.
Talk about tech...
Considering that we are going to use this README as a portfolio; it is obvious that we must talk about the projects on which we have worked as a developer.
So, creatively list your most impressive projects and clients. If you have participated in open-source projects, mention them as well. And, obviously, include in this portfolio the repositories you are most proud of.
...But not only
Talking about tech is good, it's the purpose of a portfolio. But, as we have already said, when two profiles are technically equal, it's the other skills that we will look at, notably what we call soft skills.
The soft skills are, for example, those related to communication, appearance, etc. These can make all the difference between two developers.
How to mention them in your portfolio? Well, if your English is very good, make your portfolio entirely in English (it will normally be understandable by all tech recruiters/CTOs).
If you have certifications (methodologies, techs, languages, etc.), mention them as well.
Also, if you write paragraphs of text in your portfolio README (if you do; keep them short!) and you tend to make mistakes, have it proofread. Spelling is not a sine qua non condition for hiring a developer, but it's always a plus!
The limits of the GitHub portfolio
While using GitHub to create your portfolio is a good idea, does not cost much in terms of time, and can be entertaining to do; there are however some limits to it.
The Markdown
First of all, Markdown. This language is simple, perhaps too simple. Even though you can include HTML in the README.md, it remains limited, and thus reduces the range of possibilities.
Unless you include gifs (for example), it will be complicated to add effects to make your portfolio even more attractive.
Calling on slightly more advanced features, such as with the tic-tac-toe game we saw a little earlier, is complicated because it requires the use of GitHub Actions and YAML; skills that not all developers master.
Portfolio is a double-edged sword
I have already mentioned it, but it's something worth emphasizing: using GitHub as a portfolio is a double-edged sword. Well done, it can be a very good advertisement.
On the other hand, if it is poorly done, your GitHub portfolio may cost you opportunities.
Moreover, keep in mind that everyone can access the source code of your README.md file... This is the opportunity to show that you know how to use comments.
Sources/useful links
Before I leave you and let you rush to GitHub to create your repo and your README (if you haven't already done so), here are some useful links that might interest you:
An automatic generator of a personalized README for your profile. Effective but a bit too simple and generic;
A very useful list of examples and tools to help you build your own portfolio via GitHub.
In summary
As we have seen, building a portfolio via a GitHub README can be a very good solution if you want to save time and show your work, your capabilities; especially when you are a junior.
Simple to create and effective, it is a very good tool on which a developer can rely to find contracts or missions.
However, it remains limited, and can be a double-edged sword depending on its use...
And you, have you already created a portfolio this way? Feel free to share it in the comments!
