Merge pull request #3999 from chrisfinazzo/instructions-for-el-capitan

Merge pull request 3999

site/_docs/troubleshooting.md

@@ -40,6 +40,15 @@ export PATH=$PATH:/home/private/gems/bin
 export RB_USER_INSTALL='true'
 {% endhighlight %}
 
+To install RubyGems on Gentoo:
+
+{% highlight bash %}
+sudo emerge -av dev-ruby/rubygems
+{% endhighlight %}
+
+On Windows, you may need to install [RubyInstaller
+DevKit](https://wiki.github.com/oneclick/rubyinstaller/development-kit).
+
 On Mac OS X, you may need to update RubyGems (using `sudo` only if necessary):
 
 {% highlight bash %}
@@ -66,14 +75,51 @@ Xcode.app can interfere with the command line tools downloaded above. If
 you run into this issue, upgrade Xcode and install the upgraded Command
 Line Tools.
 
-To install RubyGems on Gentoo:
+### Jekyll & Mac OS X 10.11
+
+With the introduction of System Integrity Protection, several directories
+that were previously writable are now considered system locations and are no
+longer available. Given these changes, the simplest way to get up and running
+is to install Homebrew and then use it to set up Ruby. This can be done as
+follows:
 
 {% highlight bash %}
-sudo emerge -av dev-ruby/rubygems
+ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
 {% endhighlight %}
 
-On Windows, you may need to install [RubyInstaller
-DevKit](https://wiki.github.com/oneclick/rubyinstaller/development-kit).
+Once Homebrew is installed, the second step is easy:
+
+{% highlight bash %}
+brew install ruby
+{% endhighlight %}
+
+Advanced users (with more complex needs) may find it helpful to choose one of a
+number of Ruby version managers ([RVM][], [rbenv][], [chruby][], [etc][].) in
+which to install Jekyll.
+
+[RVM]: https://rvm.io
+[rbenv]: http://rbenv.org
+[chruby]: https://github.com/postmodern/chruby
+[etc]: https://github.com/rvm/rvm/blob/master/docs/alt.md
+
+If you elect to use one of the above methods to install Ruby, it might be
+necessary to modify your `$PATH` variable using the following command:
+
+{% highlight bash %}
+export PATH=/usr/local/bin:$PATH
+{% endhighlight %}
+
+GUI apps can modify the `$PATH` as follows:
+
+{% highlight bash %}
+launchctl setenv PATH "/usr/local/bin:$PATH"
+{% endhighlight %}
+
+Either of these approaches are useful because `/usr/local` is considered a
+"safe" location on systems which have SIP enabled, they avoid potential
+conflicts with the version of Ruby included by Apple, and it keeps Jekyll and
+its dependencies in a sandboxed environment. This also has the added
+benefit of not requiring `sudo` when you want to add or remove a gem.
 
 ### Could not find a JavaScript runtime. (ExecJS::RuntimeUnavailable)