Overview
Jekyll is a static 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 the HTML site.
Installing Jekyll
The Jekyll engine must be installed and running, in order to render your site. One way to install Jekyll is to:
- 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-pagesgem 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
- Installs
- 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.
- A Gemfile which:
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 CWD.
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, 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.)
No responses yet