From b8430df6b1d4b1bc64a7f768d14f5ec05bf71dee Mon Sep 17 00:00:00 2001 From: Henry Kobin Date: Wed, 31 May 2017 07:35:54 -0700 Subject: [PATCH] windows 10 tutorial (#6100) Merge pull request 6100 --- docs/_docs/windows.md | 59 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 50 insertions(+), 9 deletions(-) diff --git a/docs/_docs/windows.md b/docs/_docs/windows.md index cc284567..b72fd836 100644 --- a/docs/_docs/windows.md +++ b/docs/_docs/windows.md @@ -8,9 +8,57 @@ Jekyll with the proper tweaks. If you are using Windows 10 Anniversary Update, the easiest way to run Jekyll is to use the new [Bash on Ubuntu on Windows](https://msdn.microsoft.com/en-us/commandline/wsl/about?f=255&MSPPError=-2147217396). For older installations, this page aims to collect some of the general knowledge and lessons that have been unearthed by Windows users. -## Installation +## Installation via Bash on Windows 10 -A quick way to install Jekyll is to follow the [installation instructions by David Burela](https://davidburela.wordpress.com/2015/11/28/easily-install-jekyll-on-windows-with-3-command-prompt-entries-and-chocolatey/): +*Please note:* You must have [Bash on Ubuntu on Windows](https://msdn.microsoft.com/en-us/commandline/wsl/about?f=255&MSPPError=-2147217396) enabled. + +First let's make sure all our packages / repositories are up to date. Open a new Command Prompt instance, and type the following: + +``` +bash +``` +Your Command Prompt instance should now be a Bash instance. Now we must update our repo lists and packages. + +``` +sudo apt-get update -y && sudo apt-get upgrade -y +``` + +Now we can install Ruby. To do this we will use a repository from [BrightBox](https://www.brightbox.com/docs/ruby/ubuntu/), which hosts optimized versions of Ruby for Ubuntu. + +``` +sudo apt-add-repository ppa:brightbox/ruby-ng +sudo apt-get update +sudo apt-get install ruby2.3 ruby2.3-dev build-essentials +``` +Next let's update our Ruby gems: + +``` +sudo gem update + +``` + +Now all that is left to do is install Jekyll. + +``` +sudo gem install jekyll bundler + +``` + +You can test by running: + +``` +jekyll new my_project +``` + +**And that's it!** +If you `cd` into the folder, you can make sure time management is working by opening your `_posts` folder. You should see a markdown file with the current date listed. + +*Please note* Bash on Ubuntu on Windows is still under development, so you may run into issues. If you see an Auto-Regeneration error warning in your Bash instance, you can ignore it. + +## Installation via Chocolatey + + +A quick way to install Jekyll using Chocolatey is to follow the [installation instructions by David Burela](https://davidburela.wordpress.com/2015/11/28/easily-install-jekyll-on-windows-with-3-command-prompt-entries-and-chocolatey/): 1. Install a package manager for Windows called [Chocolatey](https://chocolatey.org/install) 2. Install Ruby via Chocolatey: `choco install ruby -y` @@ -24,8 +72,6 @@ For a more conventional way of installing Jekyll you can follow this [complete g [windows-installjekyll3]: https://labs.sverrirs.com/jekyll/ -## 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. @@ -37,9 +83,6 @@ the site generation process. It can be done with the following command: ```sh $ chcp 65001 ``` - -## Timezone Management - Since Windows doesn't have a native source of zoneinfo data, the Ruby Interpreter would not understand IANA Timezones and hence using them had the `TZ` environment variable default to UTC/GMT 00:00. Though Windows users could alternatively define their blog's timezone by setting the key to use POSIX format of defining timezones, it wasn't as user-friendly when it came to having the clock altered to changing DST-rules. @@ -51,8 +94,6 @@ While 'new' blogs created with Jekyll v3.4 and greater, will have the following gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby] ``` -## 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