Monday, 15 April 2019

GitHub Pages and Jekyll themes

By default, a newly generated Jekyll site uses a theme called Minima. It is a simple, spartan theme with very little to recommend it, so I decided to replace it with one of the supported themes instead.

GitHub Pages Supported Themes
According to the documentation, it should be easy enough: just edit _config.yml and replace minima with the name of the new theme, jekyll-theme-tactile for example.

Actually it was not so easy because the other themes have a more simplistic layout scheme than the Minima theme, so when you serve up the site, you end up with error messages about missing layouts.

The end result is a blank screen and lots of beating your head on the keyboard.

Jekyll layouts

The default Jekyll theme minima has four built-in layouts that are used by different pages of the blog.

When you switch to one of the other GitHub Pages themes, the new theme might only have the default.html layout, so when you switch from Minima to Tactile or Cayman, for example, you will get a blank page because the other layouts are missing.

If you examine the source code of the Minima theme, you will see that there are four layout files in the _layouts folder:

  • default.html: the default base layout
  • home.html: layout for the home page
  • page.html: layout for other pages such as About, Contacts etc
  • post.html: layout for the blog posts

The first step to sorting the problem out is to copy the missing layout files from the minima theme into your own _layouts folder. Don't copy the file default.html for now, just the missing files:

├── _layouts
│   ├── home.html
│   ├── page.html
│   └── post.html

Now you can change the theme without triggering error messages and the site will be visible.

Note that the website will fall back to use the default.html layout that is baked into in the gem of the new theme that you selected, so it may or may not have the functionality you require.

The next step is to use the default.html layout file from the theme that you have chosen as the basis for improving the functionality.

I am using jekyll-theme-tactile, so copy default.html from the Tactile repo to your _layouts folder.

├── _layouts
│   ├── default.html (from the repo of the theme you selected)
│   ├── home.html    (from minima)
│   ├── page.html    (from minima)
│   └── post.html    (from minima)

Commit your changes and push to GitHub:

$ git add --all
$ git commit -m "Add missing layouts"
$ git push

You will not see any changes when you reload the website, but now you have the raw material to build a more usable site.


The first thing I did was to add a favicon to the site.

Create favicon.png from an image using GIMP or an on-line tool like faviconit, then copy the image to the root folder of your site and add this line to the <head> section of default.html:
<link rel="shortcut icon" type="image/png" href="favicon.png">
Protip: if you don't see the favicon after you have pushed to, clear your cache and refresh the page. Most browsers should respond to Ctrl+F5 to do the same thing.

Clickable title

Make the title a hyperlink to the site to make it easier to navigate back to Home by adding this line to the <header> section of the <body> of default.html:
<h1><a class="site-title" rel="author" 
      href="{{ "/" | relative_url }}">{{ site.title | escape }}</a></h1>

Further reading

Shout out to this blog post which was extremely helpful when I first hit problems with Jekyll theming.

This book Creating Blogs with Jekyll is a good guide to static website generators.

No comments:

Post a comment