Rake tasks for Jekyll

Installation

Add this line to your application’s Gemfile:

gem 'rake-jekyll'

and then execute:

$ bundle

Tasks

Deploy to Git

This task builds the Jekyll site and deploys it to a remote Git repository.

Usage

The most simple usage suitable for GitHub and Travis CI:

require 'rake-jekyll'

Rake::Jekyll::GitDeployTask.new

This listing introduces all the configurable options with their default values:

require 'rake-jekyll'

Rake::Jekyll::GitDeployTask.new(:deploy) do |t|

  # Description of the rake task.
  t.description = 'Generate the site and push changes to remote repository'

  # Overrides the *author* of the commit being created with author of the
  # source commit (i.e. HEAD in the current branch).
  t.author = -> {
    `git log -n 1 --format='%aN <%aE>'`.strip
  }
  # Overrides the *author date* of the commit being created with date of the
  # source commit.
  t.author_date = -> {
    `git log -n 1 --format='%aD'`.strip
  }
  # The commit message will contain hash of the source commit.
  t.commit_message = -> {
    "Built from #{`git rev-parse --short HEAD`.strip}"
  }
  # Use 'Jekyll' as the default *committer* name (with empty email) when the
  # user.name is not set in git config.
  t.committer = 'Jekyll'

  # Deploy the built site into remote branch named 'gh-pages', or 'master' if
  # the remote repository URL matches `#{gh_user}.github.io.git`.
  # It will be automatically created if not exist yet.
  t.deploy_branch = -> {
    gh_user = ENV['TRAVIS_REPO_SLUG'].to_s.split('/').first
    remote_url.match(/[:\/]#{gh_user}\.github\.io\.git$/) ? 'master' : 'gh-pages'
  }
  # Run this command to build the site.
  t.build_script = ->(dest_dir) {
    puts "\nRunning Jekyll..."
    sh "bundle exec jekyll build --destination #{dest_dir}"
  }
  # Use the default committer (configured in git) when available.
  t.override_committer = false

  # Use URL of the 'origin' remote to fetch/push the built site into. If env.
  # variable GH_TOKEN is set, then it adds it as a userinfo to the URL.
  t.remote_url = -> {
    url = `git config remote.origin.url`.strip.gsub(/^git:/, 'https:')
    next url.gsub(%r{^https://([^/]+)/(.*)$}, 'git@\1:\2') if ssh_key_file?
    next url.gsub(%r{^https://}, "https://#{ENV['GH_TOKEN']}@") if ENV.key? 'GH_TOKEN'
    next url
  }
  # Skip commit and push when building a pull request, env. variable
  # SKIP_DEPLOY represents truthy, or env. variable SOURCE_BRANCH is set, but
  # does not match TRAVIS_BRANCH.
  t.skip_deploy = -> {
    ENV['TRAVIS_PULL_REQUEST'].to_i > 0 ||
      %w[yes y true 1].include?(ENV['SKIP_DEPLOY'].to_s.downcase) ||
      (ENV['SOURCE_BRANCH'] && ENV['SOURCE_BRANCH'] != ENV['TRAVIS_BRANCH'])
  }
  # Path of the private SSH key to be used for communication with the
  # repository defined by remote_url.
  t.ssh_key_file = '.deploy_key'
end

Note: All options except name and description accepts both String and Proc as a value.

Setup for GitHub Pages and Travis CI

You need two branches in your repository:

• master, for markup sources and configuration. This branch can be named anything you choose.

• gh-pages, for the generated static content produced by Travis CI. This branch will be created automatically for you when the task runs.

The goal is to configure a Travis CI job to listen for commits on the master branch, automatically run the Jekyll build, and push the generated content to the gh-pages branch. After that, your site will be available at http(s)://<username>.github.io/<projectname>.

1. Create or edit file Gemfile in your Jekyll repository:

   source 'https://rubygems.org'
   
   gem 'jekyll'
   gem 'rake'
   gem 'rake-jekyll'

2. Create or edit file Rakefile in your Jekyll repository:

   require 'rake-jekyll'
   
   Rake::Jekyll::GitDeployTask.new(:deploy)

3. Install travis gem:

   $ gem install travis

4. Create file .travis.yml in the root of your Jekyll repository:

   language: ruby
   sudo: false
   rvm: 2.2.0
   script: bundle exec rake deploy

5. Enable Travis CI for your Jekyll repository:

   1. open your profile page on Travis,

   2. find the repository and turn on the switch,

   3. then click on repository settings (next to the switch) and enable “Build only if .travis.yml is present.”

Now you can choose if you want to use GitHub token (an easier way), or a deploy key (more secure way).

A. Use GitHub token

6. Generate a new personal access token on GitHub:

   1. open this page to generate a new personal access token,

   2. select the scope public_repo, fill some description and confirm.

7. Encrypt the token and add it to your .travis.yml:

   1. replace <token> with the GitHub token and execute:

      $ travis encrypt GH_TOKEN=<token> --add env.global

   2. and check that it added something like the following to .travis.yml:

      env:
        global:
          secure: YOUR-ENCRYPTED-TOKEN

8. Commit changes, push to GitHub and check that Travis has started the job and finished it successfully.

B. Use SSH deploy key

6. Generate new RSA key pair and write it to file .deploy_key (and .deploy_key.pub) in the root of your Jekyll repository:

   $ ssh-keygen -N '' -f .deploy_key

7. Encrypt the private key and add it to your .travis.yml:

   1. encrypt the key:

      $ travis encrypt-file .deploy_key --add

   2. check that it created file .deploy_key.enc and added something like the following to .travis.yml:

      before_install:
        - openssl aes-256-cbc -K $encrypted_e18dd77852c2_key -iv $encrypted_e18dd77852c2_iv -in .deploy_key.enc -out .deploy_key -d

   3. and add command chmod 600 .deploy_key to .travis.yml after the openssl command, so you will end with something like:

      before_install:
        - openssl aes-256-cbc -K $encrypted_e18dd77852c2_key -iv $encrypted_e18dd77852c2_iv -in .deploy_key.enc -out .deploy_key -d
        - chmod 600 .deploy_key

8. Add .deploy_key to .gitignore (this is unencrypted private key, keep it in secret!):

   $ echo '.deploy_key' >> .gitignore

9. Register the generated key as a deploy key in your GitHub repository:

   1. open https://github.com/<username>/<reponame>/settings/keys and click on Add deploy key,

   2. paste content of the .deploy_key.pub file to the textbox,

   3. select “Allow write access” and confirm.

10. Commit changes, push to GitHub and check that Travis has started the job and finished it successfully.

Contributing

1. Fork it.

2. Create your feature branch (git checkout -b my-new-feature).

3. Commit your changes (git commit -am 'Add some feature').

4. Push to the branch (git push origin my-new-feature).

5. Create a new Pull Request.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.