Building on GitHub Pages

So, something I didn’t know about GitHub pages. It doesn’t really support custom Jekyll themes. Sure, there’s the list here of officially supported themes. If only I knew about them before I picked a theme…

Nevertheless, I tried to push my website with this custom theme. While everything builds fine locally (I’m even using the GitHub Pages gem), GitHub Pages would refuse to build my website with the theme. It’s supposed to work if you specify remote_theme: in _config.yml.

You’ll never guess what happens. GitHub Pages builds weird What the heck is that?

Changing to Travis CI

After spending a few hours on trying to fix all the build errors (it’s really annoying to debug over email as you might imagine), I didn’t have any patience left for trying to work around GitHub Pages. After looking at some examples of other websites on GitHub, I decided to move to using Travis CI.

Changing branches

I pushed the website source onto a new “source” branch. “master” would be reserved for just build products (the contents of _site essentially). After that, setting up Travis CI was fairly straightforward.

A side note on Travis settings:

  • Travis will try to build if it detects changes to any branch, even if it doesn’t have a .travis.yml file. This can be changed from the settings on the Travis website. Too late for me though – I now have a random build failed on my master branch. ☹️ master tries to build
  • There’s an option for .travis.yml to restrict builds to specific branches. As you might guess, this is useless if you don’t have a .travis.yml on a given branch (like master).

The Final Stretch

Are we done? Wait, Font Awesome isn’t loading… no font awesome

Darn it

Oh yeah, GitHub will still try to build my web page using Jekyll so node_modules is lost. Better include a .nojekyll file.

Finished?

There’s still a lot to do:

  • Pagination is quite broken (though there are very few posts so whatever).
  • Adding tags and categories for posts might be nice.
  • The Travis build is extremely barebones at the moment.
  • More automation for creating new posts and adding new CS 61A content would be a nice to have, but definitely not essential. Maybe look into rake?
  • I should figure out something better than copying over my node_modules folder to the website.

However, I’m much happier with the new site compared to the old site. Not bad for less than one week worth of effort!

And of course, a summary

  • Changing to Travis CI rather than depending on GitHub Pages to build everything definitely required some effort, but has made debugging a lot easier. Honestly though, getting started with Travis was a lot easier than I expected.
  • Documentation for certain aspects of GitHub Pages and Jekyll is disappointingly scarce. Part of the reason I wrote all this down was for future me in case I ran into these issues again.
  • Writing HTML still isn’t fun. But Markdown is bearable.