2 files changed, 15 insertions, 6 deletions

diff --git a/docs/README.md b/docs/README.md
index fdc89d2eb7..79708c3df9 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -20,12 +20,16 @@ In this directory you will find textfiles formatted using Markdown, with an ".md
 read those text files directly if you want. Start with index.md.
 
 The markdown code can be compiled to HTML using the [Jekyll tool](http://jekyllrb.com).
-To use the `jekyll` command, you will need to have Jekyll installed. 
-The easiest way to do this is via a Ruby Gem, see the 
-[jekyll installation instructions](http://jekyllrb.com/docs/installation).
-If not already installed, you need to install `kramdown` and `jekyll-redirect-from` Gems
-with `sudo gem install kramdown jekyll-redirect-from`.
-Execute `jekyll build` from the `docs/` directory. Compiling the site with Jekyll will create a directory
+`Jekyll` and a few dependencies must be installed for this to work. We recommend
+installing via the Ruby Gem dependency manager. Since the exact HTML output 
+varies between versions of Jekyll and its dependencies, we list specific versions here
+in some cases:
+
+    $ sudo gem install jekyll -v 1.4.3
+    $ sudo gem uninstall kramdown -v 1.4.1
+    $ sudo gem install jekyll-redirect-from
+
+Execute `jekyll` from the `docs/` directory. Compiling the site with Jekyll will create a directory
 called `_site` containing index.html as well as the rest of the compiled files.
 
 You can modify the default Jekyll build as follows:
diff --git a/docs/_config.yml b/docs/_config.yml
index d3ea2625c7..7bc3a78e2d 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -3,6 +3,11 @@ markdown: kramdown
 gems:
   - jekyll-redirect-from
 
+# For some reason kramdown seems to behave differently on different
+# OS/packages wrt encoding. So we hard code this config.
+kramdown:
+  entity_output: numeric
+
 # These allow the documentation to be updated with nerw releases
 # of Spark, Scala, and Mesos.
 SPARK_VERSION: 1.0.0-SNAPSHOT