Merge pull request #375 from SethTisue/restore-global-jekyll-instructions

restore instructions for running with global Jekyll

Author: heathermiller

README.md

@@ -6,15 +6,29 @@ It's a static site generated by [Jekyll](https://github.com/mojombo/jekyll), and
 
 ## Dependencies
 
-This site uses a Jekyll, a Ruby framework. You'll need Ruby and Bundler installed; see [Jekyll installation instructions](http://jekyllrb.com/docs/installation/) for the details.
+This site uses a Jekyll, a Ruby framework. The required Jekyll version is 1.5.1.
 
-## Building & Viewing
+## Building the site
 
-cd into the directory where you cloned this repository, then install the required gems with `bundle install`. This will automatically put the gems into `./bundle-vendor/bundle`.
+There are two ways to run Jekyll to build the site:
 
-Start the server in the context of the bundle:
+* using globally installed Jekyll and accompanying gems
+* using Bundler, so Jekyll and accompanying gems are installed only inside this directory
 
-    bundle exec jekyll serve
+The former method is the one currently actually used on
+scala-lang.org. The latter method may be more convenient for users who
+are comfortable using Bundler and who don't want anything else
+installed system-wide.
+
+### Building with global Jekyll
+
+Install Jekyll 1.5.1 on your system using RubyGems:
+
+    gem install jekyll -v 1.5.1
+
+After cloning, cd into the directory where you cloned this repository and run:
+
+    jekyll serve
 
 and watch the output. You should see something like:
 
@@ -25,9 +39,16 @@ and watch the output. You should see something like:
            Generating... done.
       Auto-regeneration: enabled for '/Users/ben/src/scala-lang'
 
-The generated site is available at `http://localhost:4000`.
+### Building with Bundler
 
-Jekyll will automatically watch for changes on the filesystem. When you change a file, the console will show that jekyll is regenerating. Wait until it says `done` to refresh your browser.
+`cd` into the directory where you cloned this repository, then install the required gems with `bundle install`. This will automatically put the gems into `./bundle-vendor/bundle`.
+
+Start the server in the context of the bundle:
+
+    bundle exec jekyll serve
+
+from this point, everything else should be the same, regardless of which method
+you used to run Jekyll.
 
 ### Windows and UTF-8
 
@@ -36,6 +57,12 @@ console in which you are running jekyll can work with UTF-8 characters. As descr
 [Solving UTF problem with Jekyll on Windows](http://joseoncode.com/2011/11/27/solving-utf-problem-with-jekyll-on-windows/)
 you have to execute `chcp 65001`. This command is best added to the `jekyll.bat`-script.
 
+## Viewing the site
+
+Regardless of your method of running Jekyll, the generated site is available at `http://localhost:4000`.
+
+Jekyll will automatically watch for changes on the filesystem. When you change a file, the console will show that jekyll is regenerating. Wait until it says `done` to refresh your browser.
+
 ## YAML Front Matter
 
 The "YAML Front Matter" is nothing more than the header on each page that you intend for Jekyll to parse. It contains information such as the name of the HTML template (layout) chosen for the specific document, and the title of the document. An example YAML front matter might look like: