Installing Jekyll

Following the instructions at https://pages.github.com/, I have enabled a HTML website to be published to GitHub Pages using GitHub Desktop.  But I want to expand on this with the prescribed use of Jekyll…

Having tried to install Jekyll on Windows Subsystem for Linux via the bash method described at https://jekyllrb.com/docs/installation/windows/, I ran into problems where I could not update the Ruby gems and had errors with directory permissions.  It appeared that the instructions conflicted with the Ruby install on Ubuntu and I ended up blowing away my WSL image.  I should have paid heed to the warning: ‘Bash on Ubuntu on Windows is still under development, so you may run into issues’.

Perhaps the WSL instructions should be supplemented with the Ubuntu instructions: https://jekyllrb.com/docs/installation/ubuntu/.

Instead I am now using the following instructions on an Ubuntu VM running Ubuntu 22.10…

1. Update repository lists and packages:
   
   

sudo apt-get update -y && sudo apt-get upgrade -y

2. Install Ruby and other pre-requisites:

sudo apt-get install ruby-full build-essential zlib1g-dev

• ruby-full:https://packages.ubuntu.com/jammy/ruby-full
  Ruby interpreter 

• build-essential: https://packages.ubuntu.com/jammy/build-essential
  All the packages required to create a debian package.

• zlib1g-dev: https://packages.ubuntu.com/jammy/zlib1g-dev
  Dev libraries.
  
  

• This differs from the ‘ruby2.5 ruby2.5-dev build-essential dh-autoreconf’ advised for WSL.  Not clear why the libraries are different.

3. Avoid installing RubyGems packages (called gems) as the root user. Instead, set up a gem installation directory for your user account. The following commands will add environment variables to your ~/.bashrc file to configure the gem installation path:

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc

echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc

echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc

source ~/.bashrc

• It is this aspect that is probably missing from the WSL instructions.

• ‘This tells gem to place its gems within the user’s home folder, not in a system-wide location, and adds the local jekyll command to the user’s PATH ahead of any system-wide paths.

To activate the new exports, either close and restart Bash, logout and log back into your shell account, or run . .bashrc in the currently-running shell’, (https://jekyllrb.com/docs/troubleshooting/#no-sudo).

4. Next, update your Ruby gems:

gem update

5. Install Jekyll and gem bundler:

gem install jekyll bundler

Check your Jekyll version:

jekyll -v

For me, this has resulted in Jekyll version 4.3.1 at time of writing.

I am going to follow with https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll?platform=linux#creating-your-site, but using Visual Studio Code instead of terminal where possible.