From 335c8fcf62bfb48c3555e0cd2a8a6d89fdfd1d7e Mon Sep 17 00:00:00 2001
From: BlueberryFoxtrot <ropers+github.com@gmail.com>
Date: Thu, 12 Jan 2017 17:28:32 +0100
Subject: [PATCH] Update installation.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. Addition of *Running Jekyll on Ubuntu* section, to address Ubuntu stumbling block as per https://github.com/jekyll/jekyll/issues/5719.
2. Restructuring, and I hope I understood correctly when NodeJS/Python are/aren't required.
3. Gentler wording – it's probably not a good idea to tell punters who hit this page because they ran into trouble that installing Jekyll *is* easy and straight-forward; it *ought to be* straight-forward. (There's always the potential for pain and confusion if not all dependencies are in place.)
---
 docs/_docs/installation.md | 29 ++++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)

diff --git a/docs/_docs/installation.md b/docs/_docs/installation.md
index d264997d..bbc35fab 100644
--- a/docs/_docs/installation.md
+++ b/docs/_docs/installation.md
@@ -10,16 +10,31 @@ encountered and how we might make the process easier.
 
 ### Requirements
 
-Installing Jekyll is easy and straight-forward, but there are a few
-requirements you’ll need to make sure your system has before you start.
+Installing Jekyll ought to be straight-forward if all requirements are met.
+Before you start, make sure your system has the following:
 
-- [Ruby](https://www.ruby-lang.org/en/downloads/) (including development
+- Linux, Unix, or macOS
+- [Ruby](https://www.ruby-lang.org/en/downloads/) (including all development
   headers, v1.9.3 or above for Jekyll 2 and v2 or above for Jekyll 3)
 - [RubyGems](https://rubygems.org/pages/download)
-- Linux, Unix, or macOS
-- [NodeJS](https://nodejs.org/), or another JavaScript runtime (Jekyll 2 and
-earlier, for CoffeeScript support).
-- [Python 2.7](https://www.python.org/downloads/) (for Jekyll 2 and earlier)
+
+#### Only required for Jekyll 2 and earlier
+- [NodeJS](https://nodejs.org/), or another JavaScript runtime (for CoffeeScript support).
+- [Python 2.7](https://www.python.org/downloads/)
+
+<div class="note info">
+  <h5>Running Jekyll on Ubuntu</h5>
+  <p>
+    Users of Jekyll on Ubuntu have reported encountering 
+    <i>Could not locate Gemfile or .bundle/ directory</i> error messages at the 
+    <code>bundle exec jekyll serve</code> step in the <a href="../quickstart/">Quick-start guide</a>.
+    The likely cause is that all installation requirements have not been fully met.
+    Recent stock Ubuntu distributions require the installation of both the <code>ruby</code> and <code>ruby-all-dev</code>
+    packages, e.g. via <code>sudo apt-get install ruby ruby-all-dev</code> (RubyGems should be included in <code>ruby</code>).
+    The <code>ruby-all-dev</code> .deb package in particular contains development header files whose absence causes 
+    the above error message.
+  </p>
+</div>
 
 <div class="note info">
   <h5>Running Jekyll on Windows</h5>