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 "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-cayman"
gem "sprockets"

Create _config.yml with the following contents:

exclude: [vendor]
jekyll_admin:
  hidden_links:
#    - 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.


comments powered by Disqus