diff --git a/lib/jekyll/commands/build.rb b/lib/jekyll/commands/build.rb index 60aac03c..e688562f 100644 --- a/lib/jekyll/commands/build.rb +++ b/lib/jekyll/commands/build.rb @@ -79,7 +79,7 @@ module Jekyll end listener.start - Jekyll.logger.info "Auto-regeneration:", "enabled for '#{source}'" + Jekyll.logger.info "Auto-regeneration:", "enabled for '#{options['source']}'" unless options['serving'] trap("INT") do diff --git a/site/_data/docs.yml b/site/_data/docs.yml index 7d0a83f3..474f73fa 100644 --- a/site/_data/docs.yml +++ b/site/_data/docs.yml @@ -31,6 +31,7 @@ docs: - github-pages - deployment-methods + - continuous-integration - title: Miscellaneous docs: diff --git a/site/docs/continuous-integration.md b/site/docs/continuous-integration.md new file mode 100644 index 00000000..323921c7 --- /dev/null +++ b/site/docs/continuous-integration.md @@ -0,0 +1,176 @@ +--- +layout: docs +title: Continuous Integration +prev_section: deployment-methods +next_section: troubleshooting +permalink: /docs/continuous-integration/ +--- + +You can easily test your website build against one or more versions of Ruby. +The following guide will show you how to set up a free build environment on +[Travis][0], with [GitHub][1] integration for pull requests. Paid +alternatives exist for private repositories. + +[0]: https://travis-ci.org/ +[1]: https://github.com/ + +## 1. Enabling Travis and GitHub + +Enabling Travis builds for your GitHub repository is pretty simple: + +1. Go to your profile on travis-ci.org: https://travis-ci.org/profile/username +2. Find the repository for which you're interested in enabling builds. +3. Click the slider on the right so it says "ON" and is a dark grey. +4. Optionally configure the build by clicking on the wrench icon. Further + configuration happens in you `.travis.yml` file. More details on that + below. + +## 2. The Test Script + +The simplest test script simply runs `jekyll build` and ensures that Jekyll +doesn't fail to build the site. It doesn't check the resulting site, but it +does ensure things are built properly. + +When testing Jekyll output, there is no better tool than [html-proofer][2]. +This tool checks your resulting site to ensure all links and images exist. +Utilize it either with the convenient `htmlproof` command-line executable, +or write a Ruby script which utilizes the gem. + +### The HTML Proofer Executable + +{% highlight bash %} +#!/usr/bin/env bash + +jekyll build +htmlproof ./_site +{% endhighlight %} + +Some options can be specified via command-line switches. Check out the +`html-proofer` README for more information about these switches, or run +`htmlproof --help` locally. + +### The HTML Proofer Library + +You can also invoke `html-proofer` in Ruby scripts (e.g. in a Rakefile): + +{% highlight ruby %} +#!/usr/bin/env ruby + +require 'html/proofer' +HTML::Proofer.new("./_site").run +{% endhighlight %} + +Options are given as a second argument to `.new`, and are encoded in a +symbol-keyed Ruby Hash. More information about the configuration options, +check out `html-proofer`'s README file. + +[2]: https://github.com/gjtorikian/html-proofer + +## 3. Configuring Your Travis Builds + +This file is used to configure your Travis builds. Because Jekyll is built +with Ruby and requires RubyGems to install, we use the Ruby language build +environment. Below is a sample `.travis.yml` file, and what follows that is +an explanation of each line. + +{% highlight yaml %} +language: ruby +rvm: +- 2.1 +script: ./script/cibuild + +# branch whitelist +branches: + only: + - gh-pages # test the gh-pages branch + - /pages-(.*)/ # test every branch which starts with "pages-" + +env: + global: + - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer +{% endhighlight %} + +Ok, now for an explanation of each line: + +{% highlight yaml %} +language: ruby +{% endhighlight %} + +This line tells Travis to use a Ruby build container. It gives your script +access to Bundler, RubyGems, and and Ruby runtime. + +{% highlight yaml %} +rvm: +- 2.1 +{% endhighlight %} + +RVM is a popular Ruby Version Manager (like rbenv, chruby, etc). This +directive tells Travis the Ruby version to use when running your test +script. + +{% highlight yaml %} +script: ./script/cibuild +{% endhighlight %} + +Travis allows you to run any arbitrary shell script to test your site. One +convention is to put all scripts for your project in the `script` +directory, and to call your test script `cibuild`. This line is completely +customizable. If your script won't change much, you can write your test +incantation here directly: + +{% highlight yaml %} +script: jekyll build && htmlproof ./_site +{% endhighlight %} + +The `script` directive can be absolutely any valid shell command. + +{% highlight yaml %} +# branch whitelist +branches: + only: + - gh-pages # test the gh-pages branch + - /pages-(.*)/ # test every branch which starts with "pages-" +{% endhighlight %} + +You want to ensure the Travis builds for your site are being run only on +the branch or branches which contain your site. One means of ensuring this +isolation is including a branch whitelist in your Travis configuration +file. By specifying the `gh-pages` branch, you will ensure the associated +test script (discussed above) is only executed on site branches. If you use +a pull request flow for proposing changes, you may wish to enforce a +convention for your builds such that all branches containing edits are +prefixed, exemplified above with the `/pages-(.*)/` regular expression. + +The `branches` directive is completely optional. + +{% highlight yaml %} +env: + global: + - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer +{% endhighlight %} + +Using `html-proofer`? You'll want this environment variable. Nokogiri, used +to parse HTML files in your compiled site, comes bundled with libraries +which it must compile each time it is installed. Luckily, you can +dramatically increase the install time of Nokogiri by setting the +environment variable `NOKOGIRI_USE_SYSTEM_LIBRARIES` to `true`. + +## 4. Gotchas + +### Exclude `vendor` + +Travis bundles all gems in the `vendor` directory on its build servers, +which Jekyll will mistakenly read and explode on. To avoid this, exclude +`vendor` in your `_config.yml`: + +{% highlight yaml %} +exclude: [vendor] +{% endhighlight %} + +### Questions? + +This entire guide is open-source. Go ahead and [edit it][3] if you have a +fix or [ask for help][4] if you run into trouble and need some help. + +[3]: https://github.com/jekyll/jekyll/edit/master/site/docs/continuous-integration.md +[4]: https://github.com/jekyll/jekyll-help#how-do-i-ask-a-question