If you’re curious, an archived version of my website is on the Wayback Machine.
The starting point:
Here’s some problems I was having with my old website:
- I was tired of the aesthetic. The material design setup just felt out of place, and I wanted to go to something even simpler.
- The CSS was a mess. On top of importing two separate bootstrap libraries, I overlay a bunch of my own CSS on top. Starting fresh would be a good chance to clean this up.
- The color usage was inconsistent for key elements. Here’s a list of the
- Teal for the hero (landing).
- Blue for the navbar.
- A different blue for one of the past semester CS 61A pages.
- Black for an old navbar.
- Another blue and red for the favicon.
I had a few goals in mind when planning this redesign (roughly in order of decreasing priority):
- An even simpler, more accessible student facing resource page. This actually ended up not being too difficult. This would likely help with cleaning up the CSS mess. As an added “bonus”, I would also be changing the aesthetic for the rest of the website.
- Fewer, better pages. This didn’t mean having a one-pager website, but I felt like there were too many pages doing nothing. Also, collecting all the past CS 61A content into one page would be really nice.
- Better automation. This wasn’t an initial goal, but ended up being something I decided to add partway into the design process.
I really liked the benefits of Jekyll for my site, so I wanted to keep using it. The ability to write markdown as well as use a template engine makes it really easy to avoid HTML, the worst part of web development (I’m kidding about HTML, but only a little bit). As I would soon find out, Jekyll + GitHub Pages still had a few unpleasant surprises in store.
I decided to look around for themes, and found that whiteglass met my needs quite well. Installing a Jekyll theme is super easy, and the process for customization has been well thought out. The benefit of using a simple theme like whiteglass is that it’s really easy to add or remove page elements without having them stick out like a sore thumb.
Adding my content and adjusting for this new theme went by mostly without issues. There was a bit of a small learning curve in getting used to working with templates, but nothing that I couldn’t easily look up online.
Oh yeah. I guess pagination doesn’t work. Look at this sadness:
paginate: 9999 # TODO: pagination is broken
I use dark theme for most of my code related things (editors/terminals/etc.). I was curious how well this would translate to a website, and experimented with it a bit at this point. But sadly, the evidence seems to suggest that dark text on a light background is more visible.
Piling on the Imports
I needed to add Bootstrap and Font Awesome for some the page elements I wanted to keep from the old website. The advice on StackOverflow I found suggests using Bower. So I did:
$ bower install bootstrap-sass bower cached https://github.com/twbs/bootstrap-sass.git#3.3.7 ... <lines omitted> jquery#3.2.1 bower_components/jquery ╭─────────────────────────────────────╮ │ │ │ Update available 1.7.9 → 1.8.2 │ │ Run npm i -g bower to update │ │ │ ╰─────────────────────────────────────╯
Huh, guess I’d better update.
$ npm i -g bower npm WARN deprecated email@example.com: ...psst! Your project can stop working at any moment because its dependencies can change. Prevent this by migrating to Yarn: https://bower.io/blog/2017/how-to-migrate-away-from-bower/ /usr/local/bin/bower -> /usr/local/lib/node_modules/bower/bin/bower + firstname.lastname@example.org updated 1 package in 5.391s
Well, that doesn’t sound good. What’s a Yarn, anyways?
As it turns out, Yarn isn’t exactly a perfect replacement for Bower. This
seems pretty minor, but Yarn installs to
node_modules instead of
bower_components. I happen to want to directly include these folders in
my final website (yes, building them on the fly is probably a better
idea). Why does this matter?
A brief rant: Jekyll and default excludes
It turns out that Jekyll excludes
node_modules by default. As of time of
writing, this doesn’t appear to be documented anywhere (grumble grumble).
The only thing I could find was this pull request, where commenters happily note that their builds have been sped up by this change. While combining Jekyll with Yarn in this way might not have been standard, it would have been really nice if this consequences of this change were easier to find (ironically, someone even states that this change will “solve a lot of user pains”).
I can’t even find anything about default excludes on the Jekyll website anywhere. Sure, it’s mentioned in the changelog for v3.3.0. But the page is (perhaps rightfully) excluded from the website search as well as search engine results.
In fact, the thing that tipped me off to this problem was GitHub’s own help pages, which happens to mention:
By default, Jekyll does not build any files or directories that
- are hidden or used for backup (indicated by names that start with . or > #, or that end with ~);
- contain site content (indicated by names that start with _); or
- are excluded in the site configuration.
Note that this still conveniently doesn’t mention
One last kicker:
_config.yml offers an “include” option, which is
supposed to “force inclusion of directories and/or files”. Guess what? It
doesn’t work for
Ah, might as well. I initially used GIMP for pixel art, but decided to try making an SVG this time around (since Safari requires an SVG image for the pinned tab icon). So far, so good.
For creating the actual favicon, I tried using realfavicongenerator.net. This creates the favicon easily enough. However, the favicon has to be scaled to many different sizes, and the website does some really ugly interpolation for simple favicons like mine.
I exported the different-sized bitmaps manually through GIMP. GIMP also
lets you create the
favicon.ico file which
combines many different sized icons.
The next step
Ok, so everything has been prepped locally.
jekyll serve seems to work
without issue. What could possibly go wrong when deploying to GitHub