Mike Slinn
Mike Slinn

Setting Up Jekyll with Ubuntu or WSL

Published 2017-01-08.
Time to read: about 2 minutes.

This article is categorized under Git, Jekyll, Scripting, Ubuntu, WSL.

Here is a script I wrote in April 2020 to set up a local development environment for this website. The script uses Jekyll to assemble the website that you are currently reading.


# Installs the right version of Jekyll and all dependencies

function installGem {
  sudo -H gem install $1 -v $2 --source 'https://rubygems.org/'

yes | sudo apt install bundler make ruby ruby-dev software-properties-common zlib1g-dev

sudo -H gem update --system 3.0.6
sudo -H gem uninstall i18n jekyll jekyll-docs jekyll-sass-converter public_suffix --all

installGem jekyll-timeago 0.13.1
installGem backports 3.17.1
installGem jekyll 3.3.0
#installGem jekyll-docs 3.3.0

sudo -H gem install bundler classifier-reborn github-pages jekyll-admin jekyll-assets \
  jekyll-docs jekyll-gist jekyll-tagging jekyll-theme-architect html-proofer libz-dev sprockets

installGem jekyll-sass-converter 1.5.2
installGem i18n 0.9.5
installGem nokogiri 1.10.9

bundle install

This remainder of this article is obsolete. Follow these instructions instead.

These are my notes for setting up GitHub pages using Ubuntu or Windows Subsystem for Linux. I updated these notes Jan 3, 2018 to include instructions on jekyll-admin. Since then, Jekyll has continued to evolve and these instructions should no longer be followed. I leave this page merely for posterity's sake.

Read the docs on the github-pages gem.

Make a Gemfile with the following contents:

source "https://rubygems.org"
gem "classifier-reborn"
gem "github-pages", group: :jekyll_plugins
gem "html-proofer"
gem "jekyll"
gem 'jekyll-admin', group: :jekyll_plugins
gem "jekyll-assets"
gem "jekyll-docs"
gem "jekyll-gist"
gem "jekyll-theme-architect"
gem "sprockets"

Create _config.yml with the following contents:

exclude: [vendor]
#    - posts
#    - pages
#    - staticfiles
#    - datafiles
#    - configuration
markdown: kramdown
name: Mike Slinn, Connoisseur of Technology
permalink: /blog/:year/:month/:day/:title
plugins: [classifier-reborn, html-proofer, jekyll, jekyll-admin, jekyll-assets, jekyll-docs, jekyll-gist, jekyll-theme-cayman]
title: Mike Slinn's Blog

Ruby 2.3+ is required, but Ubuntu defaults to an older version. I set up Ruby 2.3, with the option of installing other versions and making them default. For more background, see Ruby packages for Ubuntu. I also installed various gems necessary to provide the Jekyll functionality I desired.

sudo apt-get install make software-properties-common
sudo apt-add-repository ppa:brightbox/ruby-ng
sudo apt-get update

sudo apt install ruby2.3 ruby2.3-dev ruby-switch zlib1g-dev ruby-bundler
ruby-switch --list
sudo ruby-switch --set ruby2.3

sudo gem update --system
sudo gem install bundler classifier-reborn jekyll github-pages jekyll-assets jekyll-gist \
jekyll-docs jekyll-theme-cayman html-proofer classifier-reborn jekyll-admin sprockets

sudo bundle clean --force
bundle install

Create repo userId.github.io (where userId is your GitHub user id) and clone it.

$ git clone git@github.com:userId/userId.github.io.git

$ cd userId.github.io/

Running Jekyll

Read the docs.

$ bundle exec jekyll docs

Read about how Bash on Windows does not yet support watched directories properly.

$ bundle exec jekyll serve --force_polling

For other OSes:

$ bundle exec jekyll serve

Use the --drafts option to preview draft blog posts in the _drafts directory. For Bash on Windows:

$ bundle exec jekyll serve --force_polling --drafts

For other OSes:

$ bundle exec jekyll serve --drafts

Visual Blog Editor

Many awesome Jekyll editors exist. The above instructions installed jekyll-admin. Run Jekyll as described above and navigate to http://localhost:4000/admin to access the administrative interface.

Unfortunately, jekyll-admin does not provide an WYSIWYG editor like that provided by CKEditor. I suggested this new feature.