A Little Help With Github Pages and Jekyll Themes

If you're getting started and you're stuck staring at a blank white webpage, read on.

Photo by Roman Synkevych on Unsplash

If you've been trying to make your first GitHub project website using Github Pages and Jekyll, I wager you've gone through something similar to the sequence of frustration that I did:

• You heard that GitHub Pages gives your open source project free website hosting. Nice!

• You tried to use the cool-sounding "theme chooser" described on the GitHub Pages site, only to figure out that it has been deprecated in favor of setting up a website using Jekyll. Fine.

• You configured your project's repo Settings for a Pages website served out of your repo's docs folder or a special branch.

• You installed Jekyll, created an initial site, and filled in your site's info in the _config.yml. Hello world achieved! You saw a placeholder website with the default ugly theme.

• You excitedly went on to change the theme to one of the Pages-"supported" ones by simply specifying it in _config.yml.

• You loaded up the site to take a look and got a blank white screen – both in the local preview of the site on your machine, and on GitHub (if you pushed it). Um...

I found a few pages out there describing this problem and they all tell you to start downloading files from the default Minima theme's _layouts folder into your project, which doesn't quite solve things. And nobody seems to actually explain how Jekyll themes work or why exactly a blank page is showing up.

Using Jekyll with GitHub Pages is actually quite nice, and finally I figured it out and am a happy Pages/Jekyll user. I burned some hours getting there though.

The issue is this: while in theory you can just change themes with a _config.yml change, in reality it's a little bit more complicated than that. Here are a few critical pieces of info I wish had been explained up front.

The Basics of How GitHub/Jekyll Works

Basically, GitHub/Jekyll reads your _config.yml file describing how you want your Jekyll site setup (including which theme you want to use), grabs all the standard files from the theme behind the scenes, and builds your website automatically.

This is cool because you don't have to pull a full copy of all of the theme's files into your project and keep them updated (more about this here). All you have to include is what matters to you:

• Your _config.yml file configuring your website

• .md (or .markdown) or .html files that specify the pages the site will have and their content

• Any files present in the theme that you want to override (we'll get back to this)

This means that GitHub/Jekyll does not automatically pull in the default example .md or .html files from your template. And those example files are not the same between the themes – particularly between the initial default Minima theme and all of the other Pages-official themes.

When you first install your Jekyll site using…

jekyll new --skip-bundle .

… the installation includes:

• An initial _config.hml file, for you to customize for your site

• An initial Gemfile file, which helps configure things if you want to test it locally

• index.markdown, about.markdown, and 404.html example content files

• A _posts directory containing an example blog post markdown file

Why You're Seeing a Blank Page

The critical thing to understand is that those last two items – the various .markdown and .html files – are example content pages that are specific to the Minima theme. So after installation, your example site is working well! Then when you change to any other theme in the _config.yml, the example content pages from the default theme are still there, and they are referencing files that don't exist in other themes. Result: blank white page.

Let's look in more detail. For your fresh site install, the homepage is defined by the index.markdown file. Open that file up. You'll see the line layout: home. What this means is that Jekyll will look for a home.html file in the _layouts directory to define what that page should look like. You don't actually have a _layouts directory because GitHub/Jekyll will just automatically grab that from the theme behind the scenes.

The problem is that most of themes other than Minima don't have a home.html in their _layouts folder. So when you try to load index.markdown, that lookup fails for other themes and you get the blank page.

Solving the Problem

Understanding that, the solution should be more clear. You should not start grabbing files from the Minima repo's _layouts folder, as some online guides suggest, because those files aren't intended for other themes.

Instead, you should strip out Minima's example content files, and start with the example content files for the theme you actually want to use:

• Delete index.markdown, about.markdown, 404.html, and the _posts folder.

• Pull up the repo for your chosen theme (links here)

• Download any .md, .markdown, or .html files at the toplevel, and put them into your own site's toplevel

That done, your site should now appear the way it was intended for your chosen theme, including that theme's example files to get you started.

(As a note, read this if you want to understand the purpose of the _posts folder. In theory you might want it, but most of the GitHub Pages themes don't use it...)

If you open those files, you'll see the layout html files it expects in its own _layouts folder. If you want to actually customize any of those layouts, then you can create your own _layouts folder locally with the contained files from the theme's repo, and go to town.

And of course you can create your own .markdown, .md, or .html files to create new pages, each specifying at the top which layout file it should use from that theme.

Once you get past that part, the GitHub Pages documentation starts to become helpful again, telling you how to do things like customize the CSS of your site and such. Have fun!