1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
---
title: Jekyll on Windows
permalink: /docs/installation/windows/
redirect_from:
- /docs/windows/
---
While Windows is not an officially-supported platform, it can be used to run Jekyll with the proper tweaks.
## Installing Ruby and Jekyll
### Installation via RubyInstaller
The easiest way to install Ruby and Jekyll is by using the [RubyInstaller](https://rubyinstaller.org/) for Windows.
RubyInstaller is a self-contained Windows-based installer that includes the Ruby language, an execution environment,
important documentation, and more.
We only cover RubyInstaller-2.4 and newer here. Older versions need to
[install the Devkit](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit) manually.
1. Download and install a **Ruby+Devkit** version from [RubyInstaller Downloads](https://rubyinstaller.org/downloads/).
Use default options for installation.
2. Run the `ridk install` step on the last stage of the installation wizard. This is needed for installing gems with native
extensions. You can find additional information regarding this in the
[RubyInstaller Documentation](https://github.com/oneclick/rubyinstaller2#using-the-installer-on-a-target-system).
From the options choose `MSYS2 and MINGW development tool chain`.
3. Open a new command prompt window from the start menu, so that changes to the `PATH` environment variable becomes effective.
Install Jekyll and Bundler using `gem install jekyll bundler`
4. Check if Jekyll has been installed properly: `jekyll -v`
{: .note .info}
You may receive an error when checking if Jekyll has not been installed properly. Reboot your system and run `jekyll -v` again.
If the error persists, please open a [RubyInstaller issue](https://github.com/oneclick/rubyinstaller2/issues/new).
That's it, you're ready to use Jekyll!
### Installation via Bash on Windows 10
If you are using Windows 10 version 1607 or later, another option to run Jekyll is by
[installing](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) the Windows Subsystem for Linux.
{: .note .info}
You must have [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about) enabled.
Make sure all your packages and repositories are up to date. Open a new Command Prompt or PowerShell window and type `bash`.
Your terminal should now be a Bash instance. Next, update your repository lists and packages:
```sh
sudo apt-get update -y && sudo apt-get upgrade -y
```
Next, install Ruby. To do this, let's use a repository from [BrightBox](https://www.brightbox.com/docs/ruby/ubuntu/),
which hosts optimized versions of Ruby for Ubuntu.
```sh
sudo apt-add-repository ppa:brightbox/ruby-ng
sudo apt-get update
sudo apt-get install ruby2.5 ruby2.5-dev build-essential dh-autoreconf
```
Next, update your Ruby gems:
```sh
gem update
```
Install Jekyll:
```sh
gem install jekyll bundler
```
{: .note .info}
No `sudo` here.
Check your Jekyll version:
```sh
jekyll -v
```
That's it! You're ready to start using Jekyll.
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.
<div class="note info">
<h5>Non-superuser account issues</h5>
<p>If the `jekyll new` command prints the error "Your user account isn't allowed to install to the system RubyGems", see
the "Running Jekyll as Non-Superuser" instructions in
<a href="{{ '/docs/troubleshooting/#no-sudo' | relative_url }}">Troubleshooting</a>.</p>
</div>
{: .note .info}
Bash on Ubuntu on Windows is still under development, so you may run into issues.
## Encoding
If you use UTF-8 encoding, Jekyll will break if a file starts with characters representing a [BOM](https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8). Therefore, remove this sequence of bytes if it appears at the beginning of your file.
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. Run the following:
```sh
chcp 65001
```
## Time Zone Management
Since Windows doesn't have a native source of zoneinfo data, the Ruby Interpreter doesn't understand IANA Timezones.
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 the 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).
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 gems) to enable development on Windows:
```ruby
# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
# and associated library.
platforms :mingw, :x64_mingw, :mswin, :jruby do
gem "tzinfo", ">= 1", "< 3"
gem "tzinfo-data"
end
```
## Auto Regeneration
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.1', :install_if => Gem.win_platform?
```
You have to use a [Ruby+Devkit](https://rubyinstaller.org/downloads/) version of the RubyInstaller and install
the MSYS2 build tools to successfully install the `wdm` gem.
|
