Mike Slinn

Connoisseur of Technology

Setting Up GitHub Pages with Ubuntu or WSL

2017-01-08 / All Blog posts

Here is a script I wrote in April 2020 to set up a local development environment for these GitHub Pages 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

  sudo -H gem update --system 3.0.6
  sudo -H gem uninstall i18n jekyll jekyll-docs jekyll-sass-converter public_suffix rouge --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]
#theme: 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. 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.

Contact Mike Slinn

Unless you are a recruiter, in which case you should not try to make contact!

  • Email
  • Direct: 514-418-0156
  • Mobile: 650-678-2285


The content on this web site is provided for general information purposes only and does not constitute legal or other professional advice or an opinion of any kind. Users of this web site are advised to seek specific legal advice by contacting their own legal counsel regarding any specific legal issues. Michael Slinn does not warrant or guarantee the quality, accuracy or completeness of any information on this web site. The articles published on this web site are current as of their original date of publication, but should not be relied upon as accurate, timely or fit for any particular purpose.

Accessing or using this web site does not create a client relationship. Although your use of the web site may facilitate access to or communications with Michael Slinn via e-mail or otherwise via the web site, receipt of any such communications or transmissions does not create a client relationship. Michael Slinn does not guarantee the security or confidentiality of any communications made by e-mail or otherwise through this web site.

This web site may contain links to third party web sites. Monitoring the vast information disseminated and accessible through those links is beyond Michael Slinn's resources and he does not attempt to do so. Links are provided for convenience only and Michael Slinn does not endorse the information contained in linked web sites nor guarantee its accuracy, timeliness or fitness for a particular purpose.

comments powered by Disqus

© 1976-2020, Michael Slinn. All rights reserved.