From 335c8fcf62bfb48c3555e0cd2a8a6d89fdfd1d7e Mon Sep 17 00:00:00 2001 From: BlueberryFoxtrot Date: Thu, 12 Jan 2017 17:28:32 +0100 Subject: [PATCH 1/4] 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/) + +
+
Running Jekyll on Ubuntu
+

+ Users of Jekyll on Ubuntu have reported encountering + Could not locate Gemfile or .bundle/ directory error messages at the + bundle exec jekyll serve step in the Quick-start guide. + The likely cause is that all installation requirements have not been fully met. + Recent stock Ubuntu distributions require the installation of both the ruby and ruby-all-dev + packages, e.g. via sudo apt-get install ruby ruby-all-dev (RubyGems should be included in ruby). + The ruby-all-dev .deb package in particular contains development header files whose absence causes + the above error message. +

+
Running Jekyll on Windows
From b1edaea7e8d38b9a8cd4d327ac5fab794a4898a0 Mon Sep 17 00:00:00 2001 From: Frank Taillandier Date: Tue, 24 Jan 2017 20:21:34 +0100 Subject: [PATCH 2/4] Add a note about troubleshooting on installation page --- docs/_docs/installation.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/docs/_docs/installation.md b/docs/_docs/installation.md index 0228a0f8..979279b8 100644 --- a/docs/_docs/installation.md +++ b/docs/_docs/installation.md @@ -25,16 +25,11 @@ Before you start, make sure your system has the following: - [Python 2.7](https://www.python.org/downloads/)
-
Running Jekyll on Ubuntu
+
Problems installing Jekyll?

- Users of Jekyll on Ubuntu have reported encountering - Could not locate Gemfile or .bundle/ directory error messages at the - bundle exec jekyll serve step in the Quick-start guide. - The likely cause is that all installation requirements have not been fully met. - Recent stock Ubuntu distributions require the installation of both the ruby and ruby-all-dev - packages, e.g. via sudo apt-get install ruby ruby-all-dev (RubyGems should be included in ruby). - The ruby-all-dev .deb package in particular contains development header files whose absence causes - the above error message. + Check out the troubleshooting page or + report an issue so the + Jekyll community can improve the experience for everyone.

@@ -58,10 +53,7 @@ $ gem install jekyll ``` All of Jekyll’s gem dependencies are automatically installed by the above -command, so you won’t have to worry about them at all. If you have problems -installing Jekyll, check out the [troubleshooting](../troubleshooting/) page or -[report an issue]({{ site.repository }}/issues/new) so the Jekyll -community can improve the experience for everyone. +command, so you won’t have to worry about them at all.
Installing Xcode Command-Line Tools
From 7397f305c238da1593732c0e38f1b3ef184f0f84 Mon Sep 17 00:00:00 2001 From: Frank Taillandier Date: Tue, 24 Jan 2017 20:23:01 +0100 Subject: [PATCH 3/4] Add Ubuntu section on troubleshooting --- docs/_docs/troubleshooting.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/_docs/troubleshooting.md b/docs/_docs/troubleshooting.md index aae024bd..d5f29671 100644 --- a/docs/_docs/troubleshooting.md +++ b/docs/_docs/troubleshooting.md @@ -36,6 +36,15 @@ If you installed the above - specifically on Fedora 23 - but the extensions woul sudo dnf install redhat-rpm-config ``` +On Ubuntu if you get stuck after `bundle exec jekyll serve` and see error +messages like `Could not locate Gemfile` or `.bundle/ directory`, it's likely +because all requirements have not been fully met. Recent stock Ubuntu +distributions require the installation of both the `ruby` and `ruby-all-dev` +packages: + +```sh +sudo apt-get install ruby ruby-all-dev +``` On [NearlyFreeSpeech](https://www.nearlyfreespeech.net/) you need to run the following commands before installing Jekyll: @@ -180,10 +189,10 @@ That is: defaults are overridden by options specified in `_config.yml`, and flags specified at the command-line will override all other settings specified elsewhere. -If you encounter an error in building the site, with the error message -"'0000-00-00-welcome-to-jekyll.markdown.erb' does not have a valid date in the -YAML front matter." try including the line `exclude: [vendor]` -in `_config.yml`. +If you encounter an error in building the site, with the error message +"'0000-00-00-welcome-to-jekyll.markdown.erb' does not have a valid date in the +YAML front matter." try including the line `exclude: [vendor]` +in `_config.yml`. ## Markup Problems From 65a3891ca293818d68b4d3a2c0ea2abf9b71e19f Mon Sep 17 00:00:00 2001 From: Frank Taillandier Date: Wed, 25 Jan 2017 14:10:19 +0100 Subject: [PATCH 4/4] ought to -> should props @pnn --- docs/_docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_docs/installation.md b/docs/_docs/installation.md index 979279b8..bc5c2515 100644 --- a/docs/_docs/installation.md +++ b/docs/_docs/installation.md @@ -10,7 +10,7 @@ encountered and how we might make the process easier. ### Requirements -Installing Jekyll ought to be straight-forward if all requirements are met. +Installing Jekyll should be straight-forward if all requirements are met. Before you start, make sure your system has the following: - GNU/Linux, Unix, or macOS