Further flesh out Continuous Integration guide

More information added after having some trouble getting Travis to execute with the existing explanation.

site/_docs/continuous-integration.md

@@ -34,6 +34,8 @@ 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.
 
+Save the commands you want to run and succeed in a file: `./script/cibuild`
+
 ### The HTML Proofer Executable
 
 {% highlight bash %}
@@ -48,6 +50,12 @@ 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.
 
+For example to avoid testing external sites, use this command:
+
+{% highlight bash %}
+$ bundle exec htmlproof ./_site --disable-external
+{% endhighlight %}
+
 ### The HTML Proofer Library
 
 You can also invoke `html-proofer` in Ruby scripts (e.g. in a Rakefile):
@@ -81,15 +89,21 @@ gem "jekyll"
 gem "html-proofer"
 {% endhighlight %}
 
+Your `.travis.yml` file should look like this:
 
 {% highlight yaml %}
 language: ruby
 rvm:
 - 2.1
-# Assume bundler is being used, install step will run `bundle install`.
+
+before_script:
+ - chmod +x ./script/cibuild # or do this locally and commit
+
+# Assume bundler is being used, therefore
+# the `install` step will run `bundle install` by default.
 script: ./script/cibuild
 
-# branch whitelist
+# branch whitelist, only for GitHub Pages
 branches:
   only:
   - gh-pages     # test the gh-pages branch
@@ -118,6 +132,16 @@ 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 %}
+before_script:
+ - chmod +x ./script/cibuild
+{% endhighlight %}
+
+The build script file needs to have the *executable* attribute set or
+Travis will fail with a permission denied error. You can also run this
+locally and commit the permissions directly, thus rendering this step
+irrelevant.
+
 {% highlight yaml %}
 script: ./script/cibuild
 {% endhighlight %}
@@ -136,7 +160,7 @@ script: jekyll build && htmlproof ./_site
 The `script` directive can be absolutely any valid shell command.
 
 {% highlight yaml %}
-# branch whitelist
+# branch whitelist, only for GitHub Pages
 branches:
   only:
   - gh-pages     # test the gh-pages branch
@@ -152,7 +176,8 @@ 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.
+The `branches` directive is completely optional. Travis will build from every
+push to any branch of your repo if leave it out.
 
 {% highlight yaml %}
 env:
@@ -177,10 +202,20 @@ environment variable `NOKOGIRI_USE_SYSTEM_LIBRARIES` to `true`.
 exclude: [vendor]
 {% endhighlight %}
 
+### Troubleshooting
+
+**Travis error:** *"You are trying to install in deployment mode after changing
+your Gemfile. Run bundle install elsewhere and add the updated Gemfile.lock
+to version control."*
+
+**Workaround:** Either run `bundle install` locally and commit your changes to
+`Gemfile.lock`, or remove the `Gemfile.lock` file from your repository and add
+an entry in the `.gitignore` file to avoid it from being checked in again.
+
 ### 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
+[4]: http://jekyllrb.com/help/

site/_docs/deployment-methods.md

@@ -126,7 +126,7 @@ command="$HOME/bin/rrsync <folder>",no-agent-forwarding,no-port-forwarding,no-pt
 
 Add the script ```deploy``` to the web site source folder:
 
-{% highlight shell %}
+{% highlight bash %}
 #!/bin/sh
 
 rsync -avr --rsh='ssh -p2222' --delete-after --delete-excluded   <folder> <user>@<site>:
@@ -141,7 +141,7 @@ Command line parameters are:
 
 Example command line is:
 
-{% highlight shell %}
+{% highlight bash %}
 rsync -avr --rsh='ssh -p2222' --delete-after --delete-excluded   _site/ hostuser@vrepin.org:
 {% endhighlight %}