I’m starting to add GitHub pages to this “site”, i.e. a personal page in GitHub. This page is a short collection of notes about how I managed it, especially if there were any gotchas even when following the official documentation.

Official Documentation

It’s probably best to open and read these pages first, then come back to the notes below:

Setting up

You enable GitHub pages via the Settings for your repository, where there should be a Pages option in the menu at the left hand side.

Custom domain

In brief, GitHub allows users to host pages under the owner.github.io domain, where owner is your GitHub username. You can use your own custom domain if you want. If you want to use a custom domain name you need to set up a CNAME in your own domain that points to owner.github.io.

Document structure

I have chosen to put my documents in the /docs/ subfolder in my main branch, rather than use a separate gh-pages branch, at least for now. It seems a more intuitive to just use one branch from a personal GitHub Pages site.

Deployment

Setting up the site as above has automatically created a GitHub Action that will build the site. The success (or otherwise) of these deployments can be seen in the Actions section of the repo.

Jekyll

Formatting for GitHub pages is provided by Jekyll, which can transform Markdown (and other markups) into themed websites, with little more than a few lines of YAML at the top of each page (known as Front Matter) and/or in a /docs/_config.yml file.

Defaults

  • Simply adding the index.md file in the /docs/ folder seems to have created a simple site.
  • Using a custom DNS name created a file named CNAME in the /docs/ path.

Config YAML file

The documentation seems to suggest that a _config.yml file will be created automatically; this didn’t seem to happen so I have created one manually within the /docs/ folder.

This file defines the overall look and feel for the site, albeit with a number of options pre-defined by GitHub.

Themes

There is a list of supported themes which can be specified by adding theme: jekyll-theme-NAME in _config.yml:

title: dev.joynt.co.uk
description: Home
theme: minima

However it seems that, for some of these themes at least, the version of the theme provided by GitHub is older than the main release of the theme. I wanted to try the latest minima theme, so I had to comment out theme: minima and specify a remote-theme:

#theme: minima
remote_theme: jekyll/minima

Pages sub-folder

As I created more pages, the root folder of the site started filling up. I created a _pages subfolder and moved various markdown pages into that. Sadly, when the site rebuilt they weren’t present. The fix for this was to specify the folder in the _config.yml file:

include:
  - _pages

NOTE: For the files in the _pages folder to appear in the built site directly under the root path, e.g. https://dev.joynt.co.uk/blog/, it was necessary to add permalink: <name> to the Front Matter (see below) on each page.

Front Matter

Each page in the Jekyll-themed site should have some lines of YAML at the very top, known as Front Matter.

For example, this “blog post” page has the following:

---
layout: post
title: Learning about GitHub Pages
---

Posts, Categories, Tags & Excerpts