New site on GitHub Pages!

So here it is, my new website and blog. Hosted on GitHub Pages, written in markdown, generated by Jekyll.

Why GitHub Pages?

I have wanted to create a blog for ages. I’m not sure what I am going to put in it, or if anyone will read it, but I think it will be a good idea.

I had intended to write a blogging site myself. Probably Node.js and React. But it felt like I was re-inventing the wheel, just for the sake of it. And it’s not like I have lots of free time to develop something like that. So I thought “why not use something that is already out there?”.

I didn’t want to use Wordpress as I didn’t want to spend money on hosting, or by constantly updating plugins. I briefly tried blogger.com but it felt like a lot of work, and I wasn’t sure how much longer Google will keep it around. I had heard about Github pages so I thought I’d take a look at that.

How does it work?

GitHub Pages works by taking static files from a repository and publishing them to a site on github.io. You can either write your own static html files or use a static site generator to create them for you. GitHub Pages has supports built in for Jekyll, or you can use a GitHub Action to generate and publish your site.

I decided to use Jekyll as it was well documented and seemed like the easy option (we all like easy options right?).

Getting started

Setting up the site was initially straight forward. I followed the Getting Started guide provided by GitHub. Simple create a new repository with a specially formatted name, and make some changes to the repository settings to tell GitHub to publish the site to GitHub pages. And basically that is it. Any time you push changes to the repository GitHub will automatically rebuild the site.

Running locally

If you want to run Jekyll locally to test any changes before you push them live you need to install Jekyll, which requires Ruby. This was all new to me as I have not used Ruby before but I followed the Jekyll Installation Guide. I can now run my site locally to test any changes before I publish them.

Themes and Styling

This is where I ran into problems. GitHub provide a list of Supported themes. In theory all you need to do is make a quick config change and re-running Jekyll will implement the changes. Except I seem to get lost down a rabbit hole here, with blank pages and missing styling. I think the problem was to do with the layout naming. The default theme, Minima, uses “home” as the layout for the home page, but other theses use “default”. When they couldn’t find a “home” layout they simply returned a blank page .

Another problem with the supported themes was they all felt a bit “dated”. None really looked right on mobile and after a bit of hacking around it was obvious I wasn’t going to get the features a wanted quickly, but this wasn’t helped by my lack of styling skills.

I eventually reverted my changes and stuck with the Minima theme. But the confusion didn’t end there. The documentation on the Minima GitHub Repository is for version 3, which isn’t released yet; GitHub Pages is currently using v2.5. I had to look at the source code for v2.5 to work out how to implement them.

I understand it is possible to use other Jekyll themes, or creating my own but I haven’t tried this yet. Something else to add to the todo list.

Conclusion

So here we are. I have a working website and blog, and writing a blog post is as easy as creating a new markdown file and pushing it to GitHub.

I would definitely recommend GitHub Pages to anyone looking to quickly create their own website. It is easy to get started and there is plenty of documentation and support available.

I would also consider using Jekyll on other projects away from GitHub Pages where static content generation is required.