Site Docs & Previews: Update Site Building/Previewing Docs

* New plugin: remove-html-extension falls back to /foo.html when /foo
  isn't found in `jekyll serve` mode.

* New Makefile target: `make preview` runs bundle exec jekyll serve

* Updated site docs to describe installing all required dependencies.
  Fully tested using a new install of Ubuntu Server 14.04.1

Gemfile

@@ -14,6 +14,8 @@ ruby '2.0.0'
 ## your dependencies, then nothing extra needs to be done
 group :development do
   gem 'ffi-icu'
+  ## When we upgrade to Jekyll 3.0.0 or higher, remove
+  ## _plugin/remove-html-extension.rb
   gem 'jekyll', '~>1.3.0'
   gem 'json'
   gem 'less'

Makefile

@@ -14,6 +14,10 @@ JEKYLL_LOG=._jekyll.log
 ## `make` (no arguments): just build
 default: build
 
+## `make preview`: start the built-in Jekyll preview
+preview:
+	$S bundle exec jekyll serve
+
 ## `make test`: don't build, but do run all tests
 test: pre-build-tests post-build-tests
 
@@ -93,8 +97,13 @@ build:
 
 ## Jekyll annoyingly returns success even when it emits errors and
 ## exceptions, so we'll grep its output for error strings
+#
+## FIXME: temporarily ignoring errors from WEBrick because
+## _plugin/remove-html-extension does something hackish until we upgrade
+## to Jekyll 3.0.0
 check-for-build-errors:
 	$S egrep -i '(error|warn|exception)' $(JEKYLL_LOG) \
+	    | grep -vi webrick.*filehandler \
 	    | eval $(ERROR_ON_OUTPUT)
 
 

README.md

@@ -134,73 +134,114 @@ You simply need to push additional commits on the appropriate branch of your Git
 
 Simple text changes can be previewed live on bitcoin.org. You only need to click anywhere on the page and hold your mouse button for one second. You'll then be able to edit the page just like a document. Changes will be lost as soon as the page is refreshed.
 
-#### Build Site With Jekyll From Bundler
+#### Build The Site Locally
 
-Make sure you have ruby 2.0. If you don't, we recommend
-[installing it with RVM](https://www.digitalocean.com/community/articles/how-to-install-ruby-on-rails-on-ubuntu-14-04-using-rvm),
-which can usually be done by running the following three commands:
+For anything more than simple text previews, you will need to build the
+site. If you can't do this yourself using the instructions below, please
+[open a pull request][pull request] with your suggested change and one
+of the site developers will create a preview for you.
+
+To build the site, you need to go through a one-time installation
+procedure that takes 15 to 30 minutes.  After that you can build the
+site an unlimited number of times with no extra work.
+
+##### Install The Dependencies
+
+Before building the site, you need to install the following
+dependencies and tools, which are pretty easy on any modern Linux:
+
+**Install binary libraries and tools**
+
+On recent versions of Ubuntu and Debian, you can run the following
+command to ensure you have the required libraries, headers, and tools:
+
+    sudo apt-get install build-essential git libicu-dev zlib1g-dev
+
+**Install RVM**
+
+Install RVM using either the [easy instructions](https://rvm.io/) or the
+[more secure instructions](https://rvm.io/rvm/security).
+
+Read the instructions printed to your console during setup to enable the
+`rvm` command in your shell.  After installation, you need to run the
+following command:
 
-    \curl -sSL https://get.rvm.io | bash -s stable
     source ~/.rvm/scripts/rvm
+
+**Install Ruby 2.0.0**
+
+To install Ruby 2.0.0, simply run this command:
+
     rvm install ruby-2.0.0
 
-Next, you need to install bundler, and let it install all gems you need
-to build the site. You must run the last command from within your local
-bitcoin.org repository:
+Sometimes this will find a pre-compiled Ruby package for your Linux
+distribution, but sometimes it will need to compile Ruby from scratch
+(which takes about 15 minutes).
 
-    gem install bundler
-    bundle install
+After Ruby 2.0.0 is installed, make it your default Ruby:
+
+    rvm alias create default ruby-2.0.0
 
-Finally, you can build the website in _site/:
+And tell your system to use it:
 
-    bundle exec jekyll build
+    rvm use default
 
-You can then copy the output files from _site/ to the root of your web server.
-If you have no web server, run `bundle exec jekyll serve` and visit
-http://127.0.0.1:4000/. This server requires you to add a trailing ".html"
-by hand in your browser address bar.
+(Note: you can use a different default Ruby, but you if you ever change
+your default Ruby, you must re-run the `gem install bundle` command
+described below before you can build the site. If you ever receive a
+"eval: bundle: not found" error, you failed to re-run `gem install
+bundle`.)
 
-#### Build Site With Jekyll From APT
+**Install Bundle**
 
-The instructions in the section above will ensure that you use the same
-versions of the same software we use to build the website, but you can
-also install dependencies from your Linux distribution. For example:
+When you used RVM to install Ruby, it also installed the `gem` program.
+Use that program to install bundle:
 
-Installing dependencies on Ubuntu 12.10:
+    gem install bundle
 
-    sudo apt-get install jekyll node-less ruby1.9.1-dev libicu-dev
-    sudo gem install ffi-icu
+**Install the Ruby dependencies**
 
-Installing dependencies on older Ubuntu and Debian distributions:
+Ensure you checked out the site repository as described in [Working with
+GitHub](#working-with-github). Then change directory to the top-level of
+your local repository (replace `bitcoin.org` with the full path to your local
+repository clone):
 
-    sudo apt-get install rubygems ruby1.9.1-dev build-essential libicu-dev
-    sudo gem install jekyll json less therubyracer ffi-icu
+    cd bitcoin.org
 
-Finally build the website in _site/:
+And install the necessary dependencies using Bundle:
 
-    jekyll
+    bundle install
 
-...Or `jekyll build` on recent versions. You can then copy the output files
-from _site/ to the root of your web server. If you have no web server, run
-`jekyll --server` (or `jekyll serve` on recent versions) and visit
-http://127.0.0.1:4000/. This server requires you to add a trailing ".html"
-by hand in your browser address bar.
+Note that some of the dependencies (particularly nokogiri) can take a
+long time to install on some systems, so be patient.
 
-#### Building With Make
+Once Bundle completes successfully, you can preview or build the site.
 
-After you've installed Jekyll and the other dependencies, you can
-optionally use GNU Make to automatically build the site and run several
-tests. You will first need to install Make using your package manager;
-for example:
+##### Preview The Site
 
-    sudo apt-get install make
+To preview the website in your local browser, make sure you're in the
+`bitcoin.org` directory and run the following command:
 
-Then in your local bitcoin.org repository, run one of the following
-commands:
+    make preview
+
+This will compile the site (takes 5 to 10 minutes; see the [speed up
+instructions](#fast-partial-previews-or-builds)) and then print the a message like this:
+
+    Server address: http://0.0.0.0:4000
+    Server running... press ctrl-c to stop.
+
+Visit the indicated URL in your browser to view the site.
+
+##### Build The Site
+
+To build the site exactly like we do for the deployment server, make
+sure you're in the `bitcoin.org` directory and run:
 
-    ## To just build the site, the equivalent of: bundle exec jekyll build
     make
 
+The resulting HTML for the entire site will be placed in the `_site`
+directory.  The following alternative options are available:
+
     ## After you build the site, you can run all of the tests (may take awhile)
     make test
 
@@ -210,13 +251,45 @@ commands:
     ## Or build the site and run all tests
     make all
 
-#### Partial build for faster preview
+#### Fast Partial Previews Or Builds
 
 In order to preview some changes faster, you can disable all plugins and
-languages but those you need by prefixing the `ENABLED_LANGS` and `ENABLED_PLUGINS`
-environment variables:
+languages except those you need by prefixing the `ENABLED_LANGS` and
+`ENABLED_PLUGINS` environment variables to your command line.  For
+example, do this to disable everything:
+
+    ## Fast preview, takes less than 30 seconds
+    ENABLED_PLUGINS="" ENABLED_LANGS="" make preview
 
-    ENABLED_PLUGINS="events autocrossref" ENABLED_LANGS="en fr" make all
+    ## Fast build and tests, takes less than 50 seconds
+    ## Some tests may fail in fast mode; use -i to continue despite them
+    ENABLED_PLUGINS="" ENABLED_LANGS="" make -i valid
+
+Then to enable some plugins or languages, you can add them back in.
+For example:
+
+    ## Slower (but still pretty fast) build and test
+    ENABLED_PLUGINS="events autocrossref" ENABLED_LANGS="en fr" make -i valid
+
+Plugins include:
+
+| Plugin       | Seconds | Remote APIs    | Used For
+|--------------|---------|----------------|------------------------
+| alerts       | 5       | --             | Network alert pages
+| autocrossref | 90      | --             | Developer documentation
+| contributors | 5       | GitHub.com     | Contributor listings
+| events       | 5       | Meetup.com; Google Maps | Events page
+| glossary     | 30      | --             | Developer glossary
+| redirects    | 20      | --             | Redirects from old URLs
+| releases     | 10      | --             | Bitcoin Core release notes; Download page
+| sitemap      | 0       | --             | /sitemap.xml
+
+Notes: some plugins interact with each other; for example running
+'autocrossref' and 'glossary' takes longer than running each other
+separately. Also, plugins that use remote APIs may take a long time to
+run if the API site is running slow.
+
+For a list of languages, look in the `_translations` directory.
 
 ## Developer Documentation
 
@@ -284,7 +357,11 @@ Any change in the English text can be done through a pull request on GitHub. If
 
 ### Events
 
-Events should be placed in `_events.yml` and adhere to this format:
+If you're not comfortable with GitHub pull requests, please submit an
+event using the button near the bottom of the [Events
+page](https://bitcoin.org/en/events).
+
+To create an event pull request, place the event in `_events.yml` and adhere to this format:
 
 ```
 - date: 2014-02-21

_plugins/inline-template.rb

@@ -53,7 +53,9 @@ def render(context)
 
 
 #Do nothing if plugin is disabled
-if !ENV['ENABLED_PLUGINS'].nil? and ENV['ENABLED_PLUGINS'].index('itemplate').nil?
+## Note: tested 2015-04-12 and the site actually compiles 5 seconds
+##       *faster* with this enabled, so hardcoding it to enabled for now
+if false #!ENV['ENABLED_PLUGINS'].nil? and ENV['ENABLED_PLUGINS'].index('itemplate').nil?
   print 'Inline Template (itemplate) disabled' + "\n"
   Liquid::Template.register_tag('itemplate', Jekyll::InlineTemplateBlockDisabled)
 else

_plugins/remove-html-extension.rb

@@ -0,0 +1,31 @@
+# This file is licensed under the MIT License (MIT) available on
+# http://opensource.org/licenses/MIT.
+
+# remove-html-extensions is a temporary workaround to allow the built-in
+# Jekyll server to serve files like /foo.html as /foo
+# This functonality is already part of Jekyll 3.0.0beta and this plugin
+# can be removed when we upgrade that far
+
+require 'webrick'
+include WEBrick
+
+## Code starting here taken from https://github.com/jekyll/jekyll/commit/e99a9e5821a7ba16ce42a1f5de378012f22acae0 MIT license
+
+# Custom WEBrick FileHandler servlet for serving "/file.html" at "/file"
+# when no exact match is found. This mirrors the behavior of GitHub Pages
+# and many static web server configs.
+class FileHandler < ::WEBrick::HTTPServlet::FileHandler
+  def search_file(req, res, basename)
+    if file = super
+      file
+    else
+      super(req, res, "#{basename}.html")
+    end
+  end
+end
+
+## End copied code
+
+## Horribly hackish and produces a warning, but it works and avoids us
+## having to modify Jekyll on every end-user system
+WEBrick::HTTPServlet::FileHandler = FileHandler