Now that the site is in a decent enough state that I’m happy for it to be online, I thought I’d take a second to talk about my process creating it and deploying it. It feels like redesigning your personal site is just something you do every few years. Whilst looking for inspiration I saw Brittany Chiang’s site (which is beautiful) and stumbled on an older iteration done in Jekyll, from 2018, which is still something I’d aspire to. I guess that’s what you can show for years of paying attention to design in frontend work. What do us backend engineers have to show? Overly complex deployment tools?
Speaking of, it’s probably important to note firstly that I’m a developer with quite a few years of experience, but mostly in backend work, I’ve spent a very limited amount of time working on frontend. So this should be read as a beginner’s account of creating a site with Jekyll. Actually, come to think of it I even had trouble deploying it. Thanks Bundler…
Creating
Creating a new site with Jekyll is easy enough, as the Jekyll front-page says:
~ $ gem install bundler jekyll
~ $ jekyll new my-awesome-site
~ $ cd my-awesome-site
~ $ bundle exec jekyll serve
# => Now browse to http://localhost:4000
Actually, I’d typically run it with a --watch option on the end, so it’d update when it detected changes. Unfortunately, the one file which you’ll spend most of your time editing in the early stages _config.yml, is also the one file which you’ll need to stop and start the above process for in order to see changes. It contains things like your title, description, url, logo, e.t.c. a number of these fields are more relevant when considering what theme you’ll be using.
Configuring
After trawling through a couple of Jekyll theme sites, I decided to go with Minimal Mistakes. It looked nice, I liked the idea of having a modular theme that was installable as a gem and most of all it has really extensive documentation, which I used a lot. A few other themes seem to be sort of “Hey look at this pretty thing I made isn’t it cool? You can copy the raw HTML if you want but I’m not helping you”.
Creating your site is then a matter of editing yaml config files (mainly _config.yml), adding pages (or posts) in Markdown or raw HTML and CSS if you feel inclined, and some simple templating done using a language called Liquid. Each group of pages on your site is referred to by Jekyll as a collection, the ‘out of the box’ one being _posts. These pages might use the simplest of page layouts but Minimal Mistakes has a number to choose from: single, splash, home, archive, each being a different configuration of header image with captions and having optionals like comments and social link sharing. Setting things like the path to the header image and whether to enable the author profile side panel is done using config fields at the top of the Markdown page (called front matter), before the content:
---
title: "Blog"
permalink: /blog/
layout: categories
entries_layout: grid
author_profile: true
---
Content here
Customising
The trick with all these handy site creation tools is always - how easy is it to customise the site when the configuration files can’t meet all your needs? Mostly it’s easy enough. Overwriting the HTML used by the theme in this case is a matter of looking at the content wherever the theme is installed (which can be found using bundle info minimal-mistakes-jekyll), finding the file you need to change and then replicating the path to that file in your own project’s directory with your replacement file.
Changing the CSS however, proves to be a little less neat. Simple changes can be made by copying the /assets/css/main.scss file to your project and making changes, but these prove to be small config variables rather than any real CSS. If you want to change any of the partial files that are imported by the main.scss file, you’ll need to copy the entire contents of the _sass directory, i.e. all the styling. Which of course negates the benefit of having a modular theme which can be updated. Of course an alternative is to change the style files directly where the theme gem is installed but this feels far worse.
Deploying
Jekyll is set up to be super simple to deploy to a user’s GitHub.io page, which is free to host on. However, I already had my jaspa.codes domain and wanted to make use of it, so I wanted to build and deploy it there as easily as I could. My default for deployments would be to use a CI (continuous integration) service, like Travis. But for something that doesn’t really need a lot of testing, I looked for simpler options.
The recommended way seemed to be using Git hooks: scripts which run when certain git commands execute, i.e. when I type git push also run this bash script. In any git repo initialised with git init there will be sample hook scripts installed at .git/hooks/, such as post-receive.sample. If you copy this to post-receive and fill it with your bash script, it will execute when receiving a push.
So following this guide on the Jekyll homepage, the process seems to be:
-
Set up a bare git repo on the server you want to deploy to
-
Create a
post-receivehook in that repo that will Jekyll build and output the contents to the directory your site is being hosted at, e.g./var/www/html -
On your local machine, add the server as a remote (ensuring you’ve set up ssh access to it already), i.e.
laptop$ git remote add deploy deployer@example.com:~/myrepo.git -
Now, whenever you
git push deploy master, it will also push to the server, run the post-hook and deploy the new site.
Simple enough. However, I ran into a bug that stumped me for quite a while. Not fully understanding what a bare git repo was, made the debugging process harder. For the record, a bare git repo is simply the .git directory of any normal repo you’re used to. However, it’s handy in this case as the post-receive hook creates a temporary copy of the content using git clone, to build the site, which the script finally deletes.
The error I was receiving when running the post-hook script was:
Can't find gem bundler (>= 0.a) with executable bundle (Gem::GemNotFoundException)
Wait I don’t have bundler installed? Yes I do… Nope, you don’t have the right version of bundler installed… sigh
According to a bundler blog post the issue is that in bundler version 2, it tries to seek out the exact version of bundler that was used originally, as specified in Gemfile.lock, otherwise it fails. Yeah I can’t see how that would be a problem.
Finding the following in Gemfile.lock
BUNDLED WITH
2.1.2
And then installing with
$ gem install bundler -v "2.1.2"
Fixed the problem.
Summary
I’m happy the site is up now and I can add content easily enough by simply writing up some posts Markdown style and pushing to the server to see it deployed. It feels like Jekyll is foremost for developers that want to host a free GitHub.io page with simple bio info and a few blog posts. If you have a particular design in mind and care a lot about styling, maybe look somewhere else.