Showcase your repos on Jekyll

Jekyll is a great, blog-aware, static site generator and is how I develop this website. Recently, I found github.dev, a theme for Jekyll that gives you a version of your Github profile in the form of a Jekyll blog hosted on Github pages. I thought this was a great idea and I wanted to add a similar thing to this website.

With some digging through the repo, I got my own website showcasing my Github repos on my about page and wanted to share some instructions for anybody interested in doing the same.

Retrieving the data

Jekyll can use data files like json or CSVs to retrieve data to display. This can be very helpful and is the foundation for how both I and the original repo got this working. Whether you’re hosting on Github pages or not, the data about the repos will be retrieved using json files and these are looped through to get the information needed.

Colours

The first thing you will need to do, if you want to show the language colours, is download colors.json from the original repo and add this to your _data directory in your project’s root. This simply gives a list of languages and a corresponding hex code for a colour to represent it, matching those used on Github itself.

Repo data

After this, you’ll want to retrieve the repo data using the Github API and this will give you JSON including data about all of your repos. The original repo used the jekyll-github-metadata plugin to simplify things, using an assumption about your hosting to get your username. My solution avoids this plugin and will work for any host, including but not limited to Github pages. This is what I recommend you do no matter the hosting, since it’s more portable and decouples your code from your host.

The API works very simply, head to https://api.github.com/users/[your username]/repos and you’ll get all the JSON you need. You could simply download this and you’d be good to go, but better you have it automatically downloaded everytime you build your site. This will save you the hassle of manually fetching an updated file. I did this with the jekyll-get-json plugin by placing this in my _config.yml

jekyll_get_json:
    data: repos
    json: 'https://api.github.com/users/benwtks/repos'
    cache: true

To automate this even further, I used Zapier to set up some integrations between Github and Netlify, my hosting provider. I added a ‘zap’ to “start deploy in Netlify” whenever there’s a “new repository in Github”. This means that whenever I create a repo, Zapier will tell Netlify to rebuild my website, Netlify will rebuild it and in the process, the jekyll-get-json plugin will retrieve the JSON from the API again and this will include the new repo. This will then update my website to show the new repo. Unfortunately, I couldn’t set up a similar thing for when I remove a repo but that’s okay with me.

Displaying the data

This is down to how you want to show the data, simply take the properties from the json and display them how you want. I personally did a similar thing to the original repo, using includes to break things up.

I added two includes, projects.html and repo-card.html. My projects include simply loops through each repo in the json, much like the one in the original repo.

<div class="projects">
	{% for repository in site.data.repos %}
	<div class="repo">
		{% include repo-card.html %}
	</div>
	{% endfor %}
</div>

Notice how I got the file from site.data.repos, which is where I told jekyll-get-json to put the file. I also added some lines to filter this like the include in the original repo. This used params from the _config,yml. If you do this, remember to change the loop to use this.

My repo-card include was much like the original as well, just with my own classes. I wrote my own CSS to go with this since I felt it would be easier to merge it with my own website this way. This also allowed me to use a fancy CSS grid for positioning them.

After this, all that was left was to add the projects include to my about.md and I was done!

Conclusion

If you want a quick and easy way to showcase projects on your website, this is a great way to go. It doesn’t take long to add this and once you’re done, things will automatically be added whenever you start a new project!

Ben Watkins

I'm a second year Computer Science student at the University of Southampton. You can find me on Twitter and Github. You can reach me at contact@benwtks.com