Dockerfile (with some convenience Makerules) for development, testing and serving

Dockerfile

@@ -0,0 +1,26 @@
+FROM ruby:2.4
+
+RUN apt-get update \
+  && apt-get install -y \
+    git \
+    locales \
+    make \
+    nodejs
+
+COPY . /src/gh/pages-gem
+
+RUN \
+  bundle config local.github-pages /src/gh/pages-gem && \
+  bundle install --gemfile=/src/gh/pages-gem/Gemfile
+
+RUN \
+  echo "en_US UTF-8" > /etc/locale.gen && \
+  locale-gen en-US.UTF-8
+
+ENV LANG en_US.UTF-8
+ENV LANGUAGE en_US.UTF-8
+ENV LC_ALL en_US.UTF-8
+
+WORKDIR /src/site
+
+CMD ["jekyll", "serve", "-H", "0.0.0.0", "-P", "4000"]

Makefile

@@ -0,0 +1,33 @@
+DOCKER=docker
+
+TAG=gh-pages
+
+# Build the docker image
+image:
+	${DOCKER} build -t ${TAG} .
+
+# Produce a bash shell
+shell:
+	${DOCKER} run --rm -it \
+		-p 4000:4000 \
+		-u `id -u`:`id -g` \
+		-v ${PWD}:/src/gh/pages-gem \
+		${TAG} \
+		/bin/bash
+
+# Spawn a server. Specify the path to the SITE directory by
+# exposing it using `expose SITE="../path-to-jekyll-site"` prior to calling or
+# by prepending it to the make rule e.g.: `SITE=../path-to-site make server`
+server:
+	test -d "${SITE}" || \
+		(echo -E "specify SITE e.g.: SITE=/path/to/site make server"; exit 1) && \
+	${DOCKER} run --rm -it \
+		-p 4000:4000 \
+		-u `id -u`:`id -g` \
+		-v ${PWD}:/src/gh/pages-gem \
+		-v `realpath ${SITE}`:/src/site \
+		-w /src/site \
+		${TAG}
+
+.PHONY:
+	image server shell

README.md

@@ -7,6 +7,10 @@ A simple Ruby Gem to bootstrap dependencies for setting up and maintaining a loc
 
 ## Usage
 
+One may opt for the conventional approach of using the pages-gem or the containerized approach in which a Docker container is used to provide an environment with most dependencies pre-installed.
+
+### Conventional
+
 **Important: Make sure you have Bundler > v1.14 by running `gem update bundler` in your terminal before following the next steps.**
 
 1. Add the following to your project's Gemfile:  
@@ -19,6 +23,29 @@ A simple Ruby Gem to bootstrap dependencies for setting up and maintaining a loc
 
 *Note: You are not required to install Jekyll separately. Once the `github-pages` gem is installed, you can build your site using `jekyll build`, or preview your site using `jekyll serve`.* For more information about installing Jekyll locally, please see [the GitHub Help docs on the matter](https://help.github.com/articles/using-jekyll-with-pages#installing-jekyll).
 
+### Docker
+
+Provided that Docker is installed, one may avoid the setup of additional tools within the environment by simply spawning a Docker container.
+
+1. Run `make image` from the root of the pages-gem directory to build an image which will be tagged as `gh-pages`
+2. Start an instance of the server by running either:
+  - `SITE=PATH_TO_YOUR_PROJECT make server` from the root of the `gh-pages` repository (where the Makefile resides) or
+  - ``SITE=PATH_TO_YOUR_PROJECT docker run --rm -p 4000:4000 -v `realpath ${SITE}`:/src/site gh-pages`` from any directory or
+  - `github-pages $PATH_TO_YOUR_PROJECT` from any directory when [func.sh](contrib/func.sh) has been sourced into your terminal session or
+  - `github-pages` from the directory of the Jekyll site to be previewed when [func.sh](contrib/func.sh) has been sourced into your terminal session.
+
+**Note:** the `github-pages` function may be enabled by sourcing func.sh. This can be done by appending
+
+  ```bash
+  source $PATH_TO_THIS_DIRECTORY/contrib/func.sh
+  ```
+
+to the scripts that load on initiation of a terminal session (usually `~/.bashrc` on bash or `~/.zshrc` on zsh).:
+
+>  Running of `github-pages` inside a directory of a Jekyll site spawns a [server on port 4000](http://localhost:4000). One may explicitly provide a path to a Jekyll site and a port by running `github-pages $PATH $PORT`. This approach is provided as a user-friendlier alternative to the `make server` or `docker run` invocations mentioned as the first options in step 2.
+
+> The ordering of the arguments for the `github-pages` function is based on the assumption that it is more likely to need to specify a custom path rather than a custom port.
+
 ### Command line usage
 
 The GitHub Pages gem also comes with several command-line tools, contained within the `github-pages` command.

contrib/func.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+# The github-pages function optionally takes two arguments
+#  - the first argument is the path to the Jekyll site
+#  - the second argument is the port number
+function github-pages {
+  _path=${1:-.}
+  _port=${2:-4000}
+  docker run --rm \
+    -p $_port:4000 \
+    -u `id -u`:`id -g` \
+    -v `realpath $_path`:/src/site \
+    gh-pages
+}