Merge pull request #1818 from jekyll/windows-docs

site/docs/frontmatter.md

@@ -30,7 +30,8 @@ relies on.
   <p>
     If you use UTF-8 encoding, make sure that no <code>BOM</code> header
     characters exist in your files or very, very bad things will happen to
-    Jekyll. This is especially relevant if you’re running Jekyll on Windows.
+    Jekyll. This is especially relevant if you’re running
+    <a href="../windows/">Jekyll on Windows</a>.
   </p>
 </div>
 

site/docs/installation.md

@@ -23,10 +23,9 @@ you’ll need to make sure your system has before you start.
 <div class="note info">
   <h5>Running Jekyll on Windows</h5>
   <p>
-    It is possible to get
+    While Windows is not officially supported, it is possible to get it running
-    <a href="http://www.madhur.co.in/blog/2011/09/01/runningjekyllwindows.html">
+    on Windows. Special instructions can be found on our
-    Jekyll running on Windows</a>, but the official documentation does not
+    <a href="../windows/#installation">Windows-specific docs page</a>.
-    support installation on Windows platforms.
   </p>
 </div>
 

site/docs/windows.md

@@ -0,0 +1,44 @@
+---
+layout: docs
+title: Jekyll on Windows
+prev_section: configuration
+next_section: posts
+permalink: /docs/windows/
+---
+
+While Windows is not an officially-supported platform, it can be used to run
+Jekyll with the proper tweaks. This page aims to collect some of the general
+knowledge and lessons that have been unearthed by Windows users.
+
+## Installation
+
+Madhur Ahuja has written up instructions to get
+[Jekyll running on Windows][windows-installation] and it seems to work for most.
+
+## Encoding
+
+If you use UTF-8 encoding, make sure that no `BOM` header
+characters exist in your files or very, very bad things will happen to
+Jekyll. This is especially relevant if you're running Jekyll on Windows.
+
+Additionally, you might need to change the code page of the console window to UTF-8
+in case you get a "Liquid Exception: Incompatible character encoding" error during
+the site generation process. It can be done with the following command:
+
+{% highlight bash %}
+$ chcp 65001
+{% endhighlight %}
+
+[windows-installation]: http://www.madhur.co.in/blog/2011/09/01/runningjekyllwindows.html
+
+## Auto-regeneration
+
+As of v1.3.0, Jekyll uses the `listen` gem to watch for changes when the
+`--watch` switch is specified during a build or serve. While `listen` has
+built-in support for UNIX systems, it requires an extra gem for compatibility
+with Windows. Add the following to the Gemfile for your site:
+
+{% highlight ruby %}
+require 'rbconfig'
+gem 'wdm', '~> 0.1.0' if RbConfig::CONFIG['target_os'] =~ /mswin|mingw/i
+{% endhighlight %}