Creating Websites With Jekyll and a Pre-Canned Jekyll Container Image

5 min readAug 14, 2022

Overview

Jekyll is a static website site generator with built-in support for GitHub pages. It takes content written in a given markup language (e.g. Markdown), and applies layouts and configuration to render a pretty HTML site.

For example, you might write a document that looks like this:

A webpage written in markdown with some “front matter”

Then you use the Jekyll engine to turn it into a site that looks something like this:

Jekyll brings lots of advantages, like:

You don’t need to be able to write in HTML. Jekyll will convert your markdown to HTML for you. (And even if you know HTML, markdown is much quicker to work with.)
Markdown is plain text, which makes version control really easy.
Jekyll has a simple approach to creating reusable templates and layouts. So you can use these to apply common styling, common headers, common footers, etc.
Built-in support by GitHub Pages means you can host your website on GitHub Pages, without having to pay for separate web hosting, and without having to “run” Jekyll in the cloud.
It’s very popular, and has a huge support community.
It’s free!

But You’ll Need Jekyll Running Locally

In order to develop your site locally, you’ll need to have Jekyll installed. There are a few ways to install and run Jekyll locally. One way is:

Install Ruby, which is a dependency for Jekyll.
Instal Jekyll, and it’s required Ruby Gems.
Run Jekyll.

The main issues with this approach are:

It requires quite a lot of configuration on the host machine. This might break other applications. And the dependencies can be hard to maintain.
Where’s the fun in doing it that way?

So I prefer to run Jekyll using a Docker container.

The off-the-shelf container is fine, but I found it needed a bit of work to get it running properly with GitHub Pages. Consequently, I’ve created my own Jekyll Docker image.

My Jekyll Image

This is a modified Docker container image, based on Jekyll/Jekyll. It installs all the pre-reqs needed to run with GitHub Pages, as well as for rendering sites locally. It comes pre-canned with configuration, as well as a Docker compose file.

For more details, check out my Jekyll image over at GitHub.

Image Details

It is based on Jekyll 4.2, which uses Ruby 2.7. Since 4.2.2, Jekyll uses Ruby 3 and this seems to have broken some gems.
It installs the appropriate Bundler version for managing Ruby gem dependencies.
It provides some default configuration files in /srv/config/
A Gemfile which:
- Installs github-pages gem
- webrick, which is required by Jekyll, but no longer installed by default in Ruby
- github-pages-unscramble, to allow use of plugins that aren’t on the GitHub Pages whitelist, locally.
- jekyll-spaceship, which provides various processors, like table, mathjax, mermaid
A _config.docker.yml to allow us to run locally, and expose on localhost:4000.
A docker-compose.yml for starting and serving your site through the container; it automatically sets up environment variables and volumes.

Using the Container for Initial Site Creation

Pre-reqs: that we have created the folder where our site will live, and that this folder is the current working directory.

Run the container interactively:

docker run -e "JEKYLL_ENV=docker" --rm -it -v "${PWD}:/srv/jekyll" -p 127.0.0.1:4000:4000 daz502/jekyll:latest sh

Note: the command above is using PowerShell. If you’re running this from Linux bash, you’ll only need to change {$PWD} to $PWD.

From the interactive session (attached to the container), we can perform some initial configuration:

# Initial site creation
jekyll new --force --skip-bundle .

If you have any permissions related issues running the above, e.g.

/usr/gem/gems/fileutils-1.6.0/lib/fileutils.rb:1326:in `chmod': Operation not permitted @ apply2files

Then running this will likely fix it:

chown -R jekyll:jekyll .

Now run this to copy over some default configuration to make your life easier:

# Copy default config into the working volume. 
# Preserve file attributes (i.e. jekyll owner) 
# This includes a default Gemfile.  
# We need this before we run the bundle install 
cp -p ../config/* .

At this point, make any changes you want to make to the configuration files. For example, you may wish to update the Gemfile to update jekyll and github-pages gem versions, or add any custom plugins we want to use.

If you need to update versions for GitHub Pages support, these pages will be helpful:

Now complete the site build from the container session:

bundle install
bundle update
exit

Serving the Site

Simply launch the container as follows:

docker compose up

Note that this configuration monitors for changes and automatically updates the site content.

Creating Sites With Jekyll

Checkout these links:

Awesome Plugins With Jekyll Spaceship

Jekyll Spaceship is a cool plugin for Jekyll which adds a bunch of functionality, including:

Enhanced table formatting within markdown
MathJax, e.g. for rendering equations and mathematic content.
PlantUML, to render UML content
Mermaid, to render flow charts and pie charts from code
Embedding of media content, such as Youtube, Spotify and Vimeo

It’s really important to note that GitHub Pages runs in a special safe mode, and only allows specific whitelisted plugins. Thus, if you want your Jekyll site to use additional plugins — such as Jekyll Spaceship — then you’ll need to build your site outside of GitHub Pages. Here is a custom GitHub Action that will automate the made of any Jekyll site and deploy to your GitHub Pages branch for you. (It is forked from https://github.com/jeffreytse/jekyll-deploy-action and only differs in terms of usage instructions.)

Before You Go

Please share this with anyone that you think will be interested. It might help them, and it really helps me!
Feel free to leave a comment 💬.
Follow and subscribe, so you don’t miss any of my content. Go to my Profile Page, and click on these icons:

Follow and Subscribe