Jekyll Github Pages

3 minute read

Updated:

I’ve wanted to do more blogging. No real direction or idea, just thought it would be nice to have a place to put down my thoughts on things I discover day-to-day. At the moment, it’s likely to either be cooking or programming related. For either, use of formatting is important and will be used often:

  • recipes will have warnings, ordered instruction steps, pictures, and links to other sites
  • programming will have links to documentation, code snippets, and downloads

Github Pages allows free hosting (obviously with sensible limitations, such as traffic volume, content size, etc.). My use fits their use case very well:

  • I don’t have traffic.
  • I want to use markdown, for easy authoring that can be done anywhere.
  • I am terrible with UX and web design.

Setting up github pages

I created a repository and went to the repository settings to enable github pages. It’s pretty straight forward and their docs served me well.

Jekyll

Github pages uses jekyll for setting up website. There’s a lot to take in but it’s essentially a declarative templating language.

Types of pages

There are 3 types of pages:

  • pages
  • posts
  • collections

Pages are regular pages in a site directory. Other than organizing them in a directory hierarchy, these don’t have special handling.

Posts are meant to be used for blogging. These have datetime in the filename. i.e. 2019-01-21-foo.md You create posts under a _posts directory.

Collections are used to organize multiple pages into common groups. I might use these to separate cooking and programming pages apart.

_config.yml

_config.yml is the file where site configs and defaults are configured. Defaults can be configured to only apply to specific filepaths or collections.

Liquid

Liquid is the name for the formatting language. It’s processed by Jekyll when building the page. This is how conditional or array maps are created.

Front Matter

Front Matter is the header at the top of pages that is used to configure settings. These values can be set on the page or in _config.yml as a global default. The values are used by the Liquid, on the page on layout, for formatting.

Minimal Mistakes Themes

The 8 themes native to Github Pages didn’t really catch my eye. I found the Minimal-mistakes theme and it was very slick. It has different layouts and many customizable extras. I was drawn to this theme because it supports a table of contents, based on markdown headers.

I don’t plan on writing long blogs but why wouldn’t you want navigation by headers? I guess most people write single, long-form blog entries.

Installing the theme

To install custom theme, you set the remote_theme property in _config.yml. It takes a github repository.

The gotchas I encountered was not including the jekyll-include-cache plugin. Turns out github pages includes some plugins (or whitelists them for use when required by theme). This is documented but I didn’t read carefully. It causes jekyll to fail to build.

Setting the default layout for blogs to single

The other gotcha was that the default layout is not used directly in this theme, it’s the base class for layouts to build on top of. The single layout is the one that’s recommended for a blog post. All my existing blog posts needed to be updated from default to single.

Instead to explicitly setting the layout every time, we can set up the default for _posts to use single layout.

In the _config.yml, set the defaults property:

defaults:
  # _posts
  - scope:
      path: ""
      type: posts
    values:
      layout: single
      author_profile: true
      read_time: true
      toc: true
      toc_sticky: true
      toc_label: On This Page

This sets the default values for posts. Like in Hiera (puppet), it’s the analogous to the common.yaml. Now we don’t have to repeat ourselves when files are in the _posts directory!

Updated: