From d77078518de38d2c4663659e6281ff2fec15a28d Mon Sep 17 00:00:00 2001 From: Anatol Broder Date: Sat, 10 May 2014 21:37:12 +0200 Subject: [PATCH 1/7] Add new page --- site/_data/docs.yml | 1 + site/docs/continuous-integration.md | 11 +++++++++++ 2 files changed, 12 insertions(+) create mode 100644 site/docs/continuous-integration.md 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..717a8004 --- /dev/null +++ b/site/docs/continuous-integration.md @@ -0,0 +1,11 @@ +--- +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 show how to set up a free build environment on [Travis][0]. + +[0]: https://travis-ci.org/ From 912bd84629cfe5c411c504ecc0bf0363b529bdc8 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Wed, 21 May 2014 01:31:48 -0400 Subject: [PATCH 2/7] A little more work. --- site/docs/continuous-integration.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/site/docs/continuous-integration.md b/site/docs/continuous-integration.md index 717a8004..20ae98d3 100644 --- a/site/docs/continuous-integration.md +++ b/site/docs/continuous-integration.md @@ -6,6 +6,17 @@ next_section: troubleshooting permalink: /docs/continuous-integration/ --- -You can easily test your website build against one or more versions of Ruby. The following guide show how to set up a free build environment on [Travis][0]. +You can easily test your website build against one or more versions of Ruby. +The following guide show how to set up a free build environment on [Travis][0], +with [GitHub][1] integration for pull requests. [0]: https://travis-ci.org/ +[1]: https://github.com/ + +## The Test Script + +When testing static sites, there is no better tool than [html-proofer][]. + +## The `.travis.yml` File + +## Enabling Travis and GitHub From b79be6d32027473c68df205b08eaa638e4c9f050 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Fri, 27 Jun 2014 03:53:41 -0400 Subject: [PATCH 3/7] updates to CI page. [ci skip] --- site/docs/continuous-integration.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/site/docs/continuous-integration.md b/site/docs/continuous-integration.md index 20ae98d3..5c3bc376 100644 --- a/site/docs/continuous-integration.md +++ b/site/docs/continuous-integration.md @@ -8,7 +8,8 @@ permalink: /docs/continuous-integration/ You can easily test your website build against one or more versions of Ruby. The following guide show how to set up a free build environment on [Travis][0], -with [GitHub][1] integration for pull requests. +with [GitHub][1] integration for pull requests. Paid alternatives exist for +private repositories. [0]: https://travis-ci.org/ [1]: https://github.com/ @@ -17,6 +18,11 @@ with [GitHub][1] integration for pull requests. When testing static sites, there is no better tool than [html-proofer][]. -## The `.travis.yml` File - ## Enabling Travis and GitHub + +## 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. From e2de7ab0c7ceacf46ee34ee8b71bd44cfaea2465 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Fri, 27 Jun 2014 15:25:33 -0400 Subject: [PATCH 4/7] Finish CI guide. --- site/docs/continuous-integration.md | 152 +++++++++++++++++++++++++++- 1 file changed, 150 insertions(+), 2 deletions(-) diff --git a/site/docs/continuous-integration.md b/site/docs/continuous-integration.md index 5c3bc376..6ba1dfee 100644 --- a/site/docs/continuous-integration.md +++ b/site/docs/continuous-integration.md @@ -14,11 +14,57 @@ private repositories. [0]: https://travis-ci.org/ [1]: https://github.com/ +## 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. + ## The Test Script -When testing static sites, there is no better tool than [html-proofer][]. +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. -## Enabling Travis and GitHub +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 `html-proof` command-line executable, +or write a Ruby script which utilizes the gem. + +### The `html-proof` Executable + +```bash +#!/usr/bin/env bash + +jekyll build +html-proof ./_site +``` + +Some options can be specified via command-line switches. Check out the +`html-proofer` README for more information about these switches, or run +`html-proof --help` locally. + +### The `html/proofer` Library + +You can also invoke `html-proofer` in Ruby scripts (e.g. in a Rakefile): + +```ruby +#!/usr/bin/env ruby + +require 'html/proofer' +HTML::Proofer.new("./_site").run +``` + +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 ## Configuring Your Travis Builds @@ -26,3 +72,105 @@ 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. + +```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 +``` + +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 && html-proof ./_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`. + +## 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 From bd4a8c1ce23441c6d6309a2c67ffdeaaacaf9316 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Fri, 27 Jun 2014 15:32:16 -0400 Subject: [PATCH 5/7] Fixes, fixes. --- lib/jekyll/commands/build.rb | 2 +- site/docs/continuous-integration.md | 24 ++++++++++++------------ 2 files changed, 13 insertions(+), 13 deletions(-) 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/docs/continuous-integration.md b/site/docs/continuous-integration.md index 6ba1dfee..83172968 100644 --- a/site/docs/continuous-integration.md +++ b/site/docs/continuous-integration.md @@ -14,7 +14,7 @@ private repositories. [0]: https://travis-ci.org/ [1]: https://github.com/ -## Enabling Travis and GitHub +## 1. Enabling Travis and GitHub Enabling Travis builds for your GitHub repository is pretty simple: @@ -25,7 +25,7 @@ Enabling Travis builds for your GitHub repository is pretty simple: configuration happens in you `.travis.yml` file. More details on that below. -## The Test Script +## 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 @@ -36,29 +36,29 @@ This tool checks your resulting site to ensure all links and images exist. Utilize it either with the convenient `html-proof` command-line executable, or write a Ruby script which utilizes the gem. -### The `html-proof` Executable +### The HTML Proofer Executable -```bash +{% highlight bash %} #!/usr/bin/env bash jekyll build html-proof ./_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 `html-proof --help` locally. -### The `html/proofer` Library +### The HTML Proofer Library You can also invoke `html-proofer` in Ruby scripts (e.g. in a Rakefile): -```ruby +{% 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, @@ -66,14 +66,14 @@ check out `html-proofer`'s README file. [2]: https://github.com/gjtorikian/html-proofer -## Configuring Your Travis Builds +## 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. -```yaml +{% highlight yaml %} language: ruby rvm: - 2.1 @@ -88,7 +88,7 @@ branches: env: global: - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer -``` +{% endhighlight %} Ok, now for an explanation of each line: @@ -155,7 +155,7 @@ 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`. -## Gotchas +## 4. Gotchas ### Exclude `vendor` From eab113e4f5b084fcdabf8c4bf935fa7741933e87 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Fri, 27 Jun 2014 15:43:37 -0400 Subject: [PATCH 6/7] html-proof ~> htmlproof --- site/docs/continuous-integration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/site/docs/continuous-integration.md b/site/docs/continuous-integration.md index 83172968..5fd3b53f 100644 --- a/site/docs/continuous-integration.md +++ b/site/docs/continuous-integration.md @@ -33,7 +33,7 @@ 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 `html-proof` command-line executable, +Utilize it either with the convenient `htmlproof` command-line executable, or write a Ruby script which utilizes the gem. ### The HTML Proofer Executable @@ -42,12 +42,12 @@ or write a Ruby script which utilizes the gem. #!/usr/bin/env bash jekyll build -html-proof ./_site +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 -`html-proof --help` locally. +`htmlproof --help` locally. ### The HTML Proofer Library @@ -119,7 +119,7 @@ customizable. If your script won't change much, you can write your test incantation here directly: {% highlight yaml %} -script: jekyll build && html-proof ./_site +script: jekyll build && htmlproof ./_site {% endhighlight %} The `script` directive can be absolutely any valid shell command. From 21ab9f8b9eb55cc97fcd2631a707e43f57103cf8 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Fri, 27 Jun 2014 16:35:21 -0400 Subject: [PATCH 7/7] Speak English good. h/t @gjtorikian --- site/docs/continuous-integration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/docs/continuous-integration.md b/site/docs/continuous-integration.md index 5fd3b53f..323921c7 100644 --- a/site/docs/continuous-integration.md +++ b/site/docs/continuous-integration.md @@ -7,9 +7,9 @@ permalink: /docs/continuous-integration/ --- You can easily test your website build against one or more versions of Ruby. -The following guide show how to set up a free build environment on [Travis][0], -with [GitHub][1] integration for pull requests. Paid alternatives exist for -private repositories. +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/