Skip to main content

Getting Started with Jekyll and Docker

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