Having a personal brand is important and having given several talks and written several blogs, I wanted a single place to keep and present the content. I looked at several options including Wordpress, Medium, hosting a page on google sites, having a single github repo with a wiki to even creating an app from the ground up, then I remembered Jekyll …

I first came across Jekyll a few years ago but at the time due to the purpose of the blog I decided to go with Wordpress, mainly because the blog writing is a little easier for none techies to understand. However now having the opportunity to choose the tech I wanted as it was my own blog I thought id give Jekyll another look.

Jekyll is a template engine written in Ruby, although don’t be put off if your not a Ruby developer, I didn’t write a single line of Ruby to create this blog.

Jekyll has first class support in Github Pages meaning you can store the source of the site and publish it to a web server in one place, reducing the overhead of running a blog. Hosting in Github pages is also free which is a bonus but if you want to use Jekyll features that are not supported in GitHub pages or want some better integration with a CDN you could always publish the generated site to AWS S3, s3_website is a great tool for the job.

Structure

Here is a Github repo containing a blog site that utilises Github Pages, it’s built using the Jekyll template engine and styled with the Maxima theme. The posts are written in Markdown and compiled & served from Github Pages.

A demo of that blog is available here Github Pages Demo

The blog shows examples of static pages, post generation, pagination and integration with the built in themes.

Creating a new Post

Create a new file in the _posts directory, i.e 2018-01-01-blog-awesome.md

At the top of the file you need to include metadata section that will describe what the post is about and provide information to the Jekyll engine, this metadata is called ‘Front Matter’ in the Jekyll world and is written in YAML, The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines, here is an example of the metadata:

---
layout: post
title: "Cats Blog"
date: 2018-01-01
desc: "An awesome Blog"
tags: [Awesomeness]
---

Copy the above into your post file and customise as necessary. You can add as much content as you would like after the last triple dash, the posts are written in kramdown which is a superset of Markdown for syntax guides go here kramdown QuickRef

Pushing to Github Pages

Go to settings and enable github pages for your repo. This means when you push new commits to the repo, the Github Jekyll engine will process the markdown files and render the html via the github pages url. The _site folder is never committed, this is a generated directory that is used by the Github pages web server.

Topology of the site

There are three main page templates, index.html, about.md & 404.html this shows the two variants of the page styles, raw html or Markdown. Any additional pages that are created at the top level will be added to the Navigation bar automatically.

You will notice in the example repo there is actually very little there, if you are happy with one of the standard themes then you can build out the pages of the blogs in either markdown or html. Any additional configuration is set in the _config.yml file, you can do more advanced things like extend the styling by overriding the SASS / LESS files. Allowing you to do as much or as little customisation as you like.

Summary

A couple of caveats I found whilst building the Jekyll site,

1. Only version 1 of the paginate plugin is supported in Github pages, so be careful when looking at other tutorials and docs on pagination.
2. Only certain themes are supported in Github Pages - theme list
3. Only a Subset of Plugins are supported in Github Pages - Plugins

The above is the bare minimum needed to create a blog and publish to GitHub Pages, it is possible to customise themes create your own theme, or add more plugins to enrich the generated pages, Take a look at this blog for some inspiration on what you can do with Jekyll.

Thanks again,

Alex

Visit the Jekyll site for more examples and documentation on the features available. Jekyll Documentation