= Rake tasks for Jekyll Jakub Jirutka https://github.com/jirutka[@jirutka] :page-layout: base :idprefix: ifdef::env-github[:idprefix: user-content-] :idseparator: - // custom :gem-name: rake-jekyll :gh-name: jirutka/{gem-name} :gh-branch: master :badge-style: flat
image:https://inch-ci.org/github/{gh-name}.svg?branch={gh-branch}&style={badge-style}[Inline docs, link="http://inch-ci.org/github/{gh-name}"] image:https://img.shields.io/gem/v/{gem-name}.svg?style={badge-style}[Gem Version, link="https://rubygems.org/gems/{gem-name}"] image:https://img.shields.io/badge/yard-docs-blue.svg?style={badge-style}[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/{gh-branch}"]
== 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'
This listing introduces all the configurable options with their default values:
require 'rake-jekyll'
Rake::Jekyll::GitDeployTask.new(:deploy) do |t|
t.description = 'Generate the site and push changes to remote repository'
t.author = -> {
git log -n 1 --format='%aN <%aE>'
.strip
}
t.author_date = -> {
git log -n 1 --format='%aD'
.strip
}
t.commit_message = -> {
"Built from #{git rev-parse --short HEAD
.strip}"
}
t.committer = 'Jekyll'
#{gh_user}.github.io.git
.t.deploy_branch = -> { gh_user = ENV['TRAVIS_REPO_SLUG'].to_s.split('/').first remote_url.match(/[:\/]#{gh_user}.github.io.git$/) ? 'master' : 'gh-pages' }
t.build_script = ->(dest_dir) { puts "\nRunning Jekyll..." sh "bundle exec jekyll build --destination #{dest_dir}" }
t.override_committer = false
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
}
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']) }
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:
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>
.
Gemfile
in your Jekyll repository:
+
[source, ruby]source 'https://rubygems.org'
Rakefile
in your Jekyll repository:
+
[source, ruby]require 'rake-jekyll'
.travis.yml
in the root of your Jekyll repository:
+
[source, yaml]. Enable Travis CI for your Jekyll repository: .. open your https://travis-ci.org/profile/[profile page] on Travis, .. find the repository and turn on the switch, .. 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
.travis.yml
:
.. replace <token>
with the GitHub token and execute:
+
$ travis encrypt GH_TOKEN=.travis.yml
:
+
[source, yaml]+ . Commit changes, push to GitHub and check that Travis has started the job and finished it successfully.
===== B. Use SSH deploy key
.deploy_key
(and .deploy_key.pub
) in the root of your Jekyll repository:
+
$ ssh-keygen -N '' -f .deploy_key
+
. Encrypt the private key and add it to your .travis.yml
:
.. encrypt the key:
+
$ travis encrypt-file .deploy_key --add
+
.. check that it created file .deploy_key.enc
and added something like the following to .travis.yml
:
+
[source, yaml]before_install:
chmod 600 .deploy_key
to .travis.yml
after the openssl
command, so you will end with something like:
+
[source, yaml]before_install:
+
. Add .deploy_key
to .gitignore
(this is unencrypted private key, keep it in secret!):
+
$ echo '.deploy_key' >> .gitignore
+
. Register the generated key as a deploy key in your GitHub repository:
.. open https://github.com/<username>/<reponame>/settings/keys
and click on Add deploy key,
.. paste content of the .deploy_key.pub
file to the textbox,
.. select “Allow write access” and confirm.
. Commit changes, push to GitHub and check that Travis has started the job and finished it successfully.
== Contributing
. Fork it.
. Create your feature branch (git checkout -b my-new-feature
).
. Commit your changes (git commit -am 'Add some feature'
).
. Push to the branch (git push origin my-new-feature
).
. Create a new Pull Request.
== License
This project is licensed under http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.