Setting Up GitHub Pages with Ubuntu or WSL

2017-01-08 / All Blog posts

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.

Read the docs on the github-pages gem.

Make a Gemfile with the following contents:

source ""
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-cayman"
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 (where userId is your GitHub user id) and clone it.

git clone

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.

comments powered by Disqus