Getting Started with Jekyll and Docker
Table of Contents
Jekyll is a static site generator written in Ruby by GitHub’s co-founder Tom Preston-Werner. Jekyll parses Liquid templates and content stored as Markdown to produce static content that then can be served by any web service. This markdown content is devoid of all HTML, layout, styling, and custom shortcodes often polluting the content in other blogging platforms like WordPress.
If you are looking for a good primer on Jekyll I would recommend Jekyll Bootstrap.
Docker #
Why use Docker? Jekyll in it’s basic configuration merely generates static content, but is extendable though plugins. Docker provides the benefit of being able to deploy a simple ready to start container to developers or continuously deployment services.
Docker Machine #
Linux users can skip installing Docker Machine, but will need to install Docker Compose. OS X users will need to spawn a Docker Machine instance if you don’t already have one running. Ensure you have the latest Docker Toolbox installed before proceeding.
docker-machine create --driver=virtualbox default
eval $(docker-machine env default)
Docker Compose #
Linux users will need to install docker-compose
separately as it isn’t
typically included in the Docker installation. Instructions can be found on
Docker’s website.
Jekyll Container #
Jekyll has an image in Docker Hub which makes this a breeze.
Note I am not using the GitHub Pages version of this container. If you plan
on using GitHub Pages you should change the image tag below from latest
to
pages
. The pages
image is a more accurate emulation of the Jekyll
configuration GitHub Pages utilizes.
Create a file named docker-compose.yml
, in the root of your repo and enter
the following:
version: '2'
services:
web:
image: 'jekyll/jekyll:latest'
name: jekyll
ports:
- '4000:4000'
volumes:
- ./:/srv/jekyll
networks:
default:
driver: bridge
Then start up a Docker container with Docker Compose:
docker-compose up -d
Open your preferred web browser and navigate to http://localhost:4000. We have no files yet so the web service the container uses will serve a directory listing of our mounted volume.
If you are a OS X user you won’t get responses from localhost:4000 due to
Docker running inside a Virtual Machine. Instead you will need to run
docker-machine ip default
to identify the IP of the Docker Machine or setup
port forwarding within VirtualBox. With the default
Docker Machine running,
run the following command in Terminal to setup a port forward:
VBoxManage controlvm "default" natpf1 "http,tcp,,4000,,4000"
Then you’ll be able to navigate to http://localhost:4000 as if it was being served locally.
Initialize Site #
To initialize the site we can reuse the existing Jekyll container. Execute
jekyll new . --force
in the root directory of the repo with the docker exec
command.
docker exec -it jekyll jekyll new . --force
If we refresh our browser we’ll see the recompiled default Jekyll theme and a few example pages and posts.
Commit to Source Control #
This is a good time to add a Git repository, commit the site and push the to
your repository. Replace <username>
with your GitHub account name:
git init
git add . -m "Initial Jekyll site"
git remote add origin git@github.com:<username>/<username>.github.io.git
git push -u origin master
Customizing Jekyll Configuration #
At some point you will want to update the Jekyll _config.yml
and will need to
restart the Jekyll service. To accomplish this we actually need to restart the
Docker container.
docker-compose restart