Toggle Dark Mode As a '90s kid who grew up with MySpace and Piczo, being able to customise a website with HTML and CSS was fairly natural to me. Learning how to do the same with this Jekyll site on GitHub was a bit more of a challenge, and I've certainly learned some things along the way.

If you're looking to create a static website for your portfolio or blogging, then look no further than GitHub pages. It's a fun experience, and it's completely free!

You can enable HTTPS to secure your site, you can choose your own github-based domain for free (e.g. username.github.io), and if you own a custom domain name you can set up DNS to redirect any requests to your domain to your GitHub site.

There's lots of thorough guides on how to set up GitHub Pages with Jekyll, and they explain the process better than I could.

I've included some of these resources below, so skip to the end if you're at a further stage. For the purposes of this post, I just want to share some other gems (pun intended) [1] of knowledge that you might not necessarily find on these technical 'step-by-step' guides.


Static Sites vs. Dynamic Sites

With GitHub Pages, you'll be creating a static website.

Static website = Everyone will 'see the exact same thing on each page'

Dynamic website = 'pulls content on the fly', content 'changes with the user'. [2]

e.g. a site that holds your CV (resume) vs. Amazon or a CMS system with a back-end database.


Limitations of GitHub Pages

  • You can't use it for commercial purposes.

  • Your entire GitHub Pages site repo can't be bigger than 1GB (this is quite generous, as you'd need an awful lot of images and text files to even come close to 1GB).
    • [3]

If you're a complete beginner, don't fret!

GitHub has a beginner guide that will walk you through the process of setting up your GitHub Pages site, and you can have your site up and running in less than an hour. It's actually what I did, and I don't think you should feel any shame in using it.

GitHub Pages Skills

Select a free theme for your Jekyll site - Jekyll Themes.io

If you just want a simple site - for example, you're a photographer wanting to share your portfolio - I would even argue you could stop at this point!


What is Jekyll?

Jekyll is a static site generator with built-in support for GitHub Pages.

It simplifies website creation by automating tasks and applying pre-set styles, so you can focus on your content and not have to worry about HTML (perfect for beginners).

GitHub Pages and Jekyll

"Do I need to install Jekyll locally?"

In short, no. If you create your site using the GitHub Pages Skills link, your site will be created using Jekyll (on GitHub), and you don't really need to learn how to use Jekyll.

Having said that, I would definitely recommend installing Jekyll locally with WSL2 (see below).

This is because it will allow you to auto-regenerate your site on your localhost when you make changes in real-time. Otherwise, you'll be waiting for your files to slowly upload live to your GitHub repo (containing your site) in order to see the changes you've made.

A local install of Jekyll means better version control by essentially having a 'dev' and 'prod' branch (local vs. on GitHub). Should you also wish to set up the Git CLI to commit to prod from the terminal, you can then do that seamlessly within WSL2.

In the image below, you can see that I have Jekyll installed locally via WSL2, this allows me to serve my website on my localhost (127.0.0.1:4000) and I can have the 'repo' of my site saved locally for easy access.

Jekyll on WSL2


Windows Subsystem for Linux 2 (WSL2)

Windows Subsystem for Linux (WSL) lets you install Linux and use Linux applications, utilities, and Bash command-line tools directly on Windows. It's also faster than a virtual machine or dual boot.

For installing it, you should use this Microsoft Guide - Microsoft Learn WSL

"So, why do we need WSL2 to install Jekyll?"

Jekyll is written using the Ruby programming language, and so we'll need to install both in order to use Jekyll locally. You won't actually need to learn how to use Ruby though, so don't worry.

My decision to use WSL2 for Jekyll was based off what I read online, as there are numerous discussions about how Ruby does not play nicely with Windows.

For installing Jekyll, you should refer to this guide - Jekyll Docs (refer to "Installation via Bash on Windows 10" section)

"Ok, so, how do we install Ruby?"

Check out some of the useful links below for some of the guides I used. It seemed to me that people were using slightly different methods.

For me, the easiest way of installing Ruby on WSL2 was actually to use the brew package manager for unix devices - Homebrew Package Manager

Bear in mind that it's normally recommended to add Ruby and Brew to your path environment variable after installation. This will allow you to execute commands from any directory, and prevents any possible issues with other dependencies.


USEFUL RESOURCES:

I recommend exploring these after you have set your site up.

Ralph Willgoss' Write-up

https://aregsar.com/blog/2019/how-to-customize-your-github-pages-blog-layout-in-five-minutes/

https://davemateer.com/2020/10/20/running-jekyll-on-wsl2

https://seankilleen.com/2020/07/building-my-jekyll-blog-with-ubuntu-on-wsl2/

https://simondosda.github.io/posts/2021-09-13-blog-github-pages-1-introduction.html

Additional Resources:

For adding comment sections:

  • giscus (this is what I'm using, and I would recommend it over utterances for this [4] reason)

  • utterances

Miscellaneous:

Install Jekyll on Apple Silicon (Jamstack)

It appears there may be publically available Docker images for Jekyll (I've not used this, so I can't vouch for it) - Jekyll Docker Image

If you start using Jekyll locally, do yourself a favour and install Visual Studio Code. The Github Desktop App might be helpful too.

I've yet to try these, but I've heard Pingendo and Bootstrap are useful in letting you make visual changes to your site, and providing you the resulting CSS styling which you can then just copy into your site's code.


Final thoughts / Things I wish I knew earlier:

I was initially quite confused as to which one of my site's files contained the code that said "your posts will be displayed on the index/main page". I could see the page code for it when I looked at the index page source, but there were no traces of it in the actual files of my site.

  • This is because if you don't specify a layout in your pages, Jekyll will use its own hidden "default" layout corresponding to your theme. If you want to override this layout, you should e.g. create a new layout called 'default.html' and store it inside a directory called '/_layouts' in your repo. You can then apply this layout by specifying 'layout: default' in each individual page. You can also have many layouts for certain pages of your site. You can read more about this here Jekyll Docs Overriding Theme Defaults.

GitHub Pages supports Javascript, CSS and HTML. If you see some cool styling on a website you can always 'view page source' or 'inspect' -> 'style editor' to reverse engineer and borrow ideas for your site. There's also lots of cool resources online that give example styles etc. for you to use for free; just Google something like 'Top 10 CSS/HTML/Javascript for your static website'.