Jekyll installation guide - canada-ca/design-system-systeme-conception GitHub Wiki

First, you need to install the command-line tools to be able to compile native extensions, open a terminal and run:

xcode-select --install

Jekyll requires Ruby > {{ site.data.ruby.min_version }}. macOS Catalina 10.15 comes with ruby 2.6.3, so you're fine. If you're running a previous macOS system, you'll have to install a newer version of Ruby.

To run the latest Ruby version you need to install it through Homebrew.

# Install Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

brew install ruby

Add the brew ruby path to your shell config :

export PATH=/usr/local/opt/ruby/bin:$PATH

Then relaunch your terminal and check your updated Ruby setup:

which ruby
# /usr/local/opt/ruby/bin/ruby

ruby -v
{{ site.data.ruby.current_version_output }}

Yay, we are now running current stable Ruby!

People often use rbenv to manage multiple Ruby versions. This is very useful when you need to be able to run a given Ruby version on a project.

# Install Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# Install rbenv and ruby-build
brew install rbenv

# Setup rbenv integration to your shell
rbenv init

# Check your install
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash

Restart your terminal for changes to take effect. Now you can install the Ruby version of our choice, let's go with current latest stable Ruby:

rbenv install {{ site.data.ruby.current_version }}
rbenv global {{ site.data.ruby.current_version }}
ruby -v
{{ site.data.ruby.current_version_output }}

That's it! Head over rbenv command references to learn how to use different versions of Ruby in your projects.

Now all that is left is installing Bundler and Jekyll.

gem install --user-install bundler jekyll

and then get your Ruby version using

ruby -v
{{ site.data.ruby.current_version_output }}

Then append your path file with the following, replacing the X.X with the first two digits of your Ruby version.

export PATH=$HOME/.gem/ruby/X.X.0/bin:$PATH

To check that your gem paths point to your home directory run:

gem env

And check that GEM PATHS: points to a path in your home directory

{: .note } Every time you update Ruby to a version with a different first two digits, you will need to update your path to match.

{: .note .warning} We strongly recommend against installing Ruby gems globally to avoid file permissions problems and using sudo.

Because of SIP Protections in Mojave, you must run:

sudo gem install bundler
sudo gem install -n /usr/local/bin/ jekyll

You only have to run:

sudo gem install bundler jekyll

Check out the Jekyll troubleshooting page or ask for help on our forum.

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.

The easiest way to run Jekyll is by using the RubyInstaller 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 manually.

1. Download and Install a Ruby+Devkit version from RubyInstaller 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
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 via: gem install jekyll bundler
4. Check if Jekyll installed properly: jekyll -v

That's it, you're ready to use Jekyll!

If you are using Windows 10 version 1607 or later, another option to run Jekyll is by installing the Windows Subsystem for Linux.

Note: You must have Windows Subsystem for Linux 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, 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.5 ruby2.5-dev build-essential dh-autoreconf

Next let's update our Ruby gems:

gem update

Now all that is left to do is install Jekyll.

gem install jekyll bundler

(Note: no sudo here.)

Check if Jekyll installed properly by running:

jekyll -v

And that's it!

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.

Note: Bash on Ubuntu on Windows is still under development, so you may run into issues.

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.

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:

chcp 65001

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. 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:

# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]

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:

gem 'wdm', '~> 0.1.1', :install_if => Gem.win_platform?

You have to use a Ruby+Devkit version of the RubyInstaller and install the MSYS2 build tools to successfully install the wdm gem.