I use WordPress a lot, but a couple of weeks ago I decided to rebuild one of my older sites with Jekyll (a static site editor) so that I could host it on Github pages. As I have explained before – I like to try different things so that I can continue to learn and develop.
The site is currently a static site, it doesn’t need anything dynamic, and using Github pages is another thing that I can learn from.
Binary Sun
Before going into detail – the site I was rebuilding is Binary Sun. This was originally a shareware games site – a place for me to sell my shareware games. Over the last few years the sale of my games have dropped to almost nothing – I had to renew the hosting and so I thought I would refresh the site entirely.
To keep hosting costs down I thought I would use Github Pages, which in turn suggested using Jekyll to manage the content.
Installing Jekyll
I haven’t used Jekyll before so I headed to the Jekyll website. Jekyll is a static site generator that uses Ruby, which I don’t use very often. Since Ruby seemed to be out of date I thought I would update that first. However to do this I had to install the Ruby Version Manager (RVM).
I installed RVM, which also seemed to update Git, and then went ahead to try to update Ruby itself. Only it told me that there was a problem with Homebrew so I had to reinstall that as well.
Eventually I got it working but it was quite a pain for someone who likes to avoid the command line as much as possible.
Using Jekyll
Now that I have it installed I had to setup a new project and then work out how to get it to display content.
I started with a blank site and built out a basic template. I new that I wanted to display HTML5 games so I set up a collection of games (Jekylls equivalent of WordPress Custom Post Types). To set up a collection you just create a new folder of files, and define the folder (collection) and its properties in the config.yml file.
Hosting Jekyll
For the hosting I am using Github pages. To set this up you can create a new Github project and then adjust the project settings to add a static site. Once you have the new project repository site deployment is as simple as committing a change and pushing it to Github. Once that’s done Github rebuilds the site content.
However Github has a bandwidth limit on free accounts. The easiest way to address this (that I know of) is to use Cloudflare to cache the data. Cloudflare have an awesome tutorial on setting up Cloudflare with Github pages.
Jekyll Plugins
Because I am using Github pages the site can only use a handful of carefully chosen plugins. For this site I am using Jekyll SEO Tag, and Jekyll Redirect From.
SEO Tag lets me set up basic SEO properties and takes care of optimizing various elements in the head of each page. Redirect from allows you to set up javascript redirects that can take care of things when pages are moved or deleted. Keep in mind that this is not a substitute for a proper 301 redirect – but it’s the best we can do. You can view all of the supported Github plugins on the Github support site.
Jekyll Tips
Jekyll (on Github pages) uses SASS by default but it doesn’t any support CSS autoprefixer plugins. So I made use of the Prefix Free JS library by Lea Verou.
One thing I found both interesting and helpful is that you can pass variables to included files, and then access them through the ‘include’ variable in the template. This allows the includes to act like functions – displaying different things conditionally. You can see an example here where I pass the game to be displayed as a variable to the game include – thus allowing any game to be displayed in any location.
The Binary Sun site has a lot of javascript (at least it will have once I am finished) and so I wanted to combine all the files into one. To make this happen I created an app.js file (you can name the file whatever you like), and then used the templating language to include the other js files with a relative path. To have a js file get parsed as a template file – you just have to add some Jekyll ‘Front Matter’ to the top of the file. You can see this in action in my app.js file.
To create a 404 page you just need to create a 404.md file in your Jekyll site root – and then Github Pages will take care of loading the correct 404 file for you.
Use the –incremental flag when building your site – this speeds things up a lot. Apparently it doesn’t work with all Jekyll plugins, but it seems to work fine with the ones I am using from the Github Pages plugins. The command would look like this:
jekyll serve --incremental
Decaching CSS and JS is always fun. Since Jekyll updates the entire site each time you build it you can decache your styles and scripts by appending the build time on to a query string as below:
So?
I have really enjoyed using Jekyll for this project and already have plans for using it on a second website. The ease of deployment, the fact I can host my site for free, the built in version control, the speed of development – once you get past the awkward setup (awkward for a less technical person) it’s a joy to use.
Let me know what you think on Mastodon, or BlueSky (or Twitter X if you must).
Link to this page
Thanks for reading. I'd really appreciate it if you'd link to this page if you mention it in your newsletter or on your blog.