diff --git a/.travis.yml b/.travis.yml index 83ea09bc..bf5f4ff8 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,11 +1,10 @@ language: ruby rvm: - 2.2 - - 2.3.3 - - 2.4.0 - - 2.5.0 + - 2.3 + - 2.4 + - 2.5 -before_install: gem install bundler # update bundler. script: "script/cibuild" env: global: diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..b481c8f4 --- /dev/null +++ b/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"] diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..2ad7fe46 --- /dev/null +++ b/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 diff --git a/README.md b/README.md index 489ef37d..87455013 100644 --- a/README.md +++ b/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. diff --git a/contrib/func.sh b/contrib/func.sh new file mode 100644 index 00000000..47be7ad4 --- /dev/null +++ b/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 +} diff --git a/lib/github-pages/configuration.rb b/lib/github-pages/configuration.rb index 28ea7883..a83162f6 100644 --- a/lib/github-pages/configuration.rb +++ b/lib/github-pages/configuration.rb @@ -23,6 +23,7 @@ class Configuration "hard_wrap" => false, "gfm_quirks" => "paragraph_end", }, + "exclude" => ["CNAME"], }.freeze # User-overwritable defaults used only in production for practical reasons @@ -100,24 +101,14 @@ def effective_config(user_config) .fix_common_issues .add_default_collections + exclude_cname(config) + # Merge overwrites into user config config = Jekyll::Utils.deep_merge_hashes config, OVERRIDES restrict_and_config_markdown_processor(config) - # Ensure we have those gems we want. - config["plugins"] = Array(config["plugins"]) | DEFAULT_PLUGINS - - # To minimize erorrs, lazy-require jekyll-remote-theme if requested by the user - config["plugins"].push("jekyll-remote-theme") if config.key? "remote_theme" - - if disable_whitelist? - config["whitelist"] = config["whitelist"] | config["plugins"] - end - - if development? - config["whitelist"] = config["whitelist"] | DEVELOPMENT_PLUGINS - end + configure_plugins(config) config end @@ -158,6 +149,29 @@ def restrict_and_config_markdown_processor(config) } end + # If the user's 'exclude' config is the default, also exclude the CNAME + def exclude_cname(config) + return unless config["exclude"].eql? Jekyll::Configuration::DEFAULTS["exclude"] + config["exclude"].concat(DEFAULTS["exclude"]) + end + + # Requires default plugins and configures whitelist in development + def configure_plugins(config) + # Ensure we have those gems we want. + config["plugins"] = Array(config["plugins"]) | DEFAULT_PLUGINS + + # To minimize erorrs, lazy-require jekyll-remote-theme if requested by the user + config["plugins"].push("jekyll-remote-theme") if config.key? "remote_theme" + + return unless development? + + if disable_whitelist? + config["whitelist"] = config["whitelist"] | config["plugins"] + end + + config["whitelist"] = config["whitelist"] | DEVELOPMENT_PLUGINS + end + # Print the versions for github-pages and jekyll to the debug # stream for debugging purposes. See by running Jekyll with '--verbose' def debug_print_versions diff --git a/spec/github-pages/configuration_spec.rb b/spec/github-pages/configuration_spec.rb index 470ac386..393b29e0 100644 --- a/spec/github-pages/configuration_spec.rb +++ b/spec/github-pages/configuration_spec.rb @@ -58,6 +58,10 @@ expect(effective_config["testing"]).to eql("123") end + it "sets exclude directive" do + expect(effective_config["exclude"]).to include("CNAME") + end + context "markdown processor" do context "with no markdown processor set" do it "defaults to kramdown" do