ashmaroli
jekyllbot
parent
6c88e5c241
commit
88e7943084
|
|
@ -3,17 +3,19 @@ title: Jekyll on Windows
|
|||
permalink: /docs/windows/
|
||||
---
|
||||
|
||||
While Windows is not an officially-supported platform, it can be used to run
|
||||
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/install_guide).
|
||||
For older installations, this page aims to collect some of the general knowledge and lessons that have been unearthed by Windows users.
|
||||
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 via Bash on Windows 10
|
||||
|
||||
*Please note:* You must have [Bash on Ubuntu on Windows](https://msdn.microsoft.com/en-us/commandline/wsl/about?f=255&MSPPError=-2147217396) enabled.
|
||||
## Installing Jekyll
|
||||
|
||||
First let's make sure all our packages / repositories are up to date.
|
||||
Open a new Command Prompt instance, and type the following:
|
||||
If you are using Windows 10 Anniversary Update, the easiest way to run Jekyll is by [installing][WSL-Guide] the new Bash on Ubuntu on Windows.
|
||||
|
||||
|
||||
### Installation via Bash on Windows 10
|
||||
|
||||
*Note:* You must have [Bash on Ubuntu on Windows][BASH-WSL] 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
|
||||
|
|
@ -23,7 +25,6 @@ Your Command Prompt instance should now be a Bash instance. Now we must update o
|
|||
```
|
||||
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.
|
||||
|
||||
```
|
||||
|
|
@ -31,6 +32,7 @@ sudo apt-add-repository ppa:brightbox/ruby-ng
|
|||
sudo apt-get update
|
||||
sudo apt-get install ruby2.3 ruby2.3-dev build-essential
|
||||
```
|
||||
|
||||
Next let's update our Ruby gems:
|
||||
|
||||
```
|
||||
|
|
@ -43,7 +45,7 @@ Now all that is left to do is install Jekyll.
|
|||
sudo gem install jekyll bundler
|
||||
```
|
||||
|
||||
Check to see if your installation worked.
|
||||
Check if Jekyll installed properly by running:
|
||||
|
||||
```
|
||||
jekyll -v
|
||||
|
|
@ -51,23 +53,38 @@ jekyll -v
|
|||
|
||||
**And that's it!**
|
||||
|
||||
To start a new project, just run:
|
||||
To start a new project named `my_blog`, just run:
|
||||
|
||||
```
|
||||
jekyll new my_project
|
||||
jekyll new my_blog
|
||||
```
|
||||
|
||||
replacing `my_project` with the name of your website.
|
||||
You can make sure time management is working properly by inspecting your `_posts` folder. You should see a markdown file with the current date in the filename.
|
||||
|
||||
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.
|
||||
**Note:** Bash on Ubuntu on Windows is still under development, so you may run into issues.
|
||||
|
||||
*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
|
||||
[WSL-Guide]: https://msdn.microsoft.com/en-us/commandline/wsl/install_guide
|
||||
[BASH-WSL]: https://msdn.microsoft.com/en-us/commandline/wsl/about
|
||||
|
||||
|
||||
### Installation via RubyInstaller
|
||||
|
||||
[RubyInstaller][] is a self-contained Windows-based installer that includes the Ruby language, an execution environment, important documentation, and more.
|
||||
|
||||
1. Download and Install a package manager version from [RubyInstaller Downloads][RubyInstaller-downloads].
|
||||
2. Install Jekyll and Bundler via a command prompt window: `gem install jekyll bundler`
|
||||
3. Check if Jekyll installed properly: `jekyll -v`
|
||||
|
||||
[RubyInstaller]: https://rubyinstaller.org/
|
||||
[RubyInstaller-downloads]: https://rubyinstaller.org/downloads/
|
||||
|
||||
|
||||
### 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)
|
||||
1. Install a package manager for Windows called [Chocolatey][]
|
||||
2. Install Ruby via Chocolatey: `choco install ruby -y`
|
||||
3. Reopen a command prompt and install Jekyll: `gem install jekyll`
|
||||
|
||||
|
|
@ -75,26 +92,12 @@ Updates in the infrastructure of Ruby may cause SSL errors when attempting to us
|
|||
|
||||
[ssl-certificate-update]: http://guides.rubygems.org/ssl-certificate-update/#installing-using-update-packages
|
||||
|
||||
For a more conventional way of installing Jekyll you can follow this [complete guide to install Jekyll 3 on Windows by Sverrir Sigmundarson][windows-installjekyll3].
|
||||
|
||||
[windows-installjekyll3]: https://labs.sverrirs.com/jekyll/
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
$ chcp 65001
|
||||
```
|
||||
|
||||
## How to install github-pages (Chocolatey Method)
|
||||
### Installing *github-pages* via Chocolatey
|
||||
|
||||
This section is part of an article written by [Jens Willmer][jwillmerPost]. To follow the instructions you need to have [Chocolatey][] installed on your system. If you already have a version of Ruby installed you need to uninstall it before you can continue.
|
||||
|
||||
|
||||
#### Install Ruby and Ruby development kit
|
||||
|
||||
Open a command prompt and execute the following commands:
|
||||
|
|
@ -102,6 +105,7 @@ Open a command prompt and execute the following commands:
|
|||
* `choco install ruby -version 2.2.4`
|
||||
* `choco install ruby2.devkit` - _needed for compilation of json gem_
|
||||
|
||||
|
||||
#### Configure Ruby development kit
|
||||
|
||||
The development kit did not set the environment path for Ruby so we need to do it.
|
||||
|
|
@ -111,14 +115,13 @@ The development kit did not set the environment path for Ruby so we need to do i
|
|||
* Edit the `config.yml` file and include the path to Ruby `- C:/tools/ruby22`
|
||||
* Execute the following command to set the path: `ruby dk.rb install`
|
||||
|
||||
|
||||
#### Nokogiri gem installation
|
||||
|
||||
This gem is also needed in the github-pages and to get it running on Windows x64 we have to install a few things.
|
||||
|
||||
|
||||
**Note:** In the current [pre release][nokogiriFails] it works out of the box with Windows x64 but this version is not referenced in the github-pages.
|
||||
|
||||
|
||||
`choco install libxml2 -Source "https://www.nuget.org/api/v2/"`{:.language-ruby}
|
||||
|
||||
`choco install libxslt -Source "https://www.nuget.org/api/v2/"`{:.language-ruby}
|
||||
|
|
@ -151,35 +154,47 @@ gem 'github-pages', group: :jekyll_plugins
|
|||
* Open a command prompt, target your local blog repository root, and install github-pages: `bundle install`
|
||||
|
||||
|
||||
After this process you should have github-pages installed on your system and you can host your blog again with `jekyll s`. \\
|
||||
After this process you should have github-pages installed on your system and you can host your blog again with `jekyll s`.
|
||||
There will be a warning on startup that you should include `gem 'wdm', '>= 0.1.0' if Gem.win_platform?` to your `Gemfile` but I could not get `jekyll s` working if I include that line so for the moment I ignore that warning.
|
||||
|
||||
In the future the installation process of the github-pages should be as simple as the setup of the blog. But as long as the new version of the Nokogiri ([v1.6.8][nokogiriReleases]) is not stable and referenced, it is work to get it up and running on Windows.
|
||||
|
||||
[jwillmerPost]: https://jwillmer.de/blog/tutorial/how-to-install-jekyll-and-pages-gem-on-windows-10-x46 "Installation instructions by Jens Willmer"
|
||||
[Chocolatey]: https://chocolatey.org/install "Package manager for Windows"
|
||||
[nokogiriFails]: https://github.com/sparklemotion/nokogiri/issues/1456#issuecomment-206481794 "Nokogiri fails to install on Ruby 2.3 for Windows"
|
||||
[Bundler]: http://bundler.io/ "Ruby Dependencie Manager"
|
||||
[nokogiriReleases]: https://github.com/sparklemotion/nokogiri/releases "Nokogiri Releases"
|
||||
[nokogiriFails]: https://github.com/sparklemotion/nokogiri/issues/1456#issuecomment-206481794 "Nokogiri fails to install on Ruby 2.3 for Windows"
|
||||
|
||||
---
|
||||
|
||||
For a more conventional way of installing Jekyll you can follow this [complete guide to install Jekyll 3 on Windows by Sverrir Sigmundarson][windows-installjekyll3].
|
||||
|
||||
Optionally you can use [Autoinstall Jekyll for Windows][fastjekyll-autoinstall].
|
||||
|
||||
---
|
||||
|
||||
[windows-installjekyll3]: https://labs.sverrirs.com/jekyll/
|
||||
[fastjekyll-autoinstall]: https://github.com/KeJunMao/fastjekyll#autoinstall-jekyll-for-windows
|
||||
|
||||
|
||||
## Encoding
|
||||
|
||||
## Installation via RubyInstaller
|
||||
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 when you're running Jekyll on Windows.
|
||||
|
||||
RubyInstaller is a self-contained Windows-based installer that includes the Ruby language, an execution environment, important documentation, and more.
|
||||
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:
|
||||
|
||||
1. Install a package manager for Windows called [RubyInstaller](https://rubyinstaller.org/).
|
||||
2. Install Jekyll and Bundler via a command prompt window: `gem install jekyll bundler`
|
||||
3. Check if the installation is accessible: `jekyll -v`
|
||||
|
||||
Optionally you can use [Autoinstall Jekyll for Windows](https://github.com/KeJunMao/fastjekyll#autoinstall-jekyll-for-windows).
|
||||
```sh
|
||||
$ chcp 65001
|
||||
```
|
||||
|
||||
|
||||
## Time-Zone 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.
|
||||
|
||||
Jekyll now uses a rubygem to internally configure Timezone based on established [IANA Timezone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
|
||||
Jekyll now uses a rubygem to internally configure Timezone based on established [IANA Timezone Database][IANA-database].
|
||||
While 'new' blogs created with Jekyll v3.4 and greater, will have the following added to their 'Gemfile' by default, existing sites *will* have to update their 'Gemfile' (and installed) to enable development on Windows:
|
||||
|
||||
```ruby
|
||||
|
|
@ -187,11 +202,14 @@ While 'new' blogs created with Jekyll v3.4 and greater, will have the following
|
|||
gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
|
||||
```
|
||||
|
||||
[IANA-database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
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 may require an extra gem for compatibility with Windows.
|
||||
|
||||
Add the following to the Gemfile for your site if you have issues with auto-regeneration on Windows alone:
|
||||
|
||||
```ruby
|
||||
gem 'wdm', '~> 0.1.0' if Gem.win_platform?
|
||||
|
|
|
|||
Loading…
Reference in New Issue