Mike Slinn
Mike Slinn

Setting Up Jekyll with Ubuntu or WSL

Published 2017-01-08. Last modified 2022-12-02.
Time to read: 2 minutes.

This page is part of the jekyll collection.

These are my notes for setting up Jekyll using Ubuntu or Windows Subsystem for Linux. They assume that the instructions in Setting Up a Ruby Development Environment were previously followed.

Update 2023-12-02

Jekyll v4.3.2 uses v2.6.3 of the json gem. v2.7.0 of the json gem was released December 01, 2023. This broke Jekyll, causing Jekyll to crash when reloading a modified site with this error:

gems/json-2.7.0/lib/json/common.rb:614:in `dump': wrong number of arguments (given 0, expected 1..3) (ArgumentError).

Ensure that a compatible version of the json gem is loaded by specifying version 2.6.3 in your Jekyll website’s Gemfile, as shown in the following instructions.

Make a Gemfile with the following contents:

Shell
source "https://rubygems.org"

gem 'jekyll'
gem 'json', '=2.6.3' # Remove this entry when Jekyll 4.3.3+ is released

group :jekyll_plugins do
  gem 'jekyll-admin', '>= 0.1.1'
  gem 'jekyll-assets', git: 'https://github.com/envygeeks/jekyll-assets'
  gem 'jekyll-docs'
  gem 'jekyll-redirect-from'
  gem 'jekyll-seo-tag'
  gem 'jekyll-sitemap'
  gem 'jekyll-sort'
  gem 'jekyll-tagging'
  gem 'kramdown'
end

group :test, :development do
  gem 'debase', "0.2.5.beta2", require: false
  gem 'ruby-debug-ide', require: false
  gem 'rake', require: false
  gem 'rubocop', require: false
  gem 'rubocop-performance', require: false
  gem 'rubocop-rake', require: false
  gem 'rspec', require: false
end

jekyll-assets has not released a new gem since Nov 13, 2018. The most recent gem, v3.0.12, has dependencies with serious security issues. Until a new jekyll-assets gem is released, use the unstable mechanism shown above to build and install the gem from git HEAD. Building from head uses more recent dependencies, and thereby avoids the security issues.

Here are the security issues for the current version of jekyll-assets:

Shell
$ bundle audit
Name: rack
Version: 1.6.13
CVE: CVE-2020-8161
GHSA: GHSA-5f9h-9pjv-v6j7
Criticality: High
URL: https://groups.google.com/forum/#!topic/ruby-security-ann/T4ZIsfRf2eA
Title: Directory traversal in Rack::Directory app bundled with Rack
Solution: upgrade to '~> 2.1.3', '>= 2.2.0'
Name: rack Version: 1.6.13 CVE: CVE-2020-8184 GHSA: GHSA-j6w9-fv6q-3q52 Criticality: High URL: https://groups.google.com/g/rubyonrails-security/c/OWtmozPH9Ak Title: Percent-encoded cookies can be used to overwrite existing prefixed cookie names Solution: upgrade to '~> 2.1.4', '>= 2.2.3'
Name: rack Version: 1.6.13 CVE: CVE-2022-30122 GHSA: GHSA-hxqx-xwvh-44m2 Criticality: High URL: https://groups.google.com/g/ruby-security-ann/c/L2Axto442qk Title: Denial of Service Vulnerability in Rack Multipart Parsing Solution: upgrade to '~> 2.0.9, >= 2.0.9.1', '~> 2.1.4, >= 2.1.4.1', '>= 2.2.3.1'
Name: rack Version: 1.6.13 CVE: CVE-2022-30123 GHSA: GHSA-wq4h-7r42-5hrr Criticality: Critical URL: https://groups.google.com/g/ruby-security-ann/c/LWB10kWzag8 Title: Possible shell escape sequence injection vulnerability in Rack Solution: upgrade to '~> 2.0.9, >= 2.0.9.1', '~> 2.1.4, >= 2.1.4.1', '>= 2.2.3.1'
Name: rack Version: 1.6.13 CVE: CVE-2022-44570 GHSA: GHSA-65f5-mfpf-vfhj Criticality: Unknown URL: https://github.com/rack/rack/releases/tag/v3.0.4.1 Title: Denial of service via header parsing in Rack Solution: upgrade to '~> 2.0.9, >= 2.0.9.2', '~> 2.1.4, >= 2.1.4.2', '~> 2.2.6, >= 2.2.6.2', '>= 3.0.4.1'
Name: rack Version: 1.6.13 CVE: CVE-2022-44571 GHSA: GHSA-93pm-5p5f-3ghx Criticality: Unknown URL: https://github.com/rack/rack/releases/tag/v3.0.4.1 Title: Denial of Service Vulnerability in Rack Content-Disposition parsing Solution: upgrade to '~> 2.0.9, >= 2.0.9.2', '~> 2.1.4, >= 2.1.4.2', '~> 2.2.6, >= 2.2.6.1', '>= 3.0.4.1'
Name: rack Version: 1.6.13 CVE: CVE-2022-44572 GHSA: GHSA-rqv2-275x-2jq5 Criticality: Unknown URL: https://github.com/rack/rack/releases/tag/v3.0.4.1 Title: Denial of service via multipart parsing in Rack Solution: upgrade to '~> 2.0.9, >= 2.0.9.2', '~> 2.1.4, >= 2.1.4.2', '~> 2.2.6, >= 2.2.6.1', '>= 3.0.4.1'
Name: sinatra Version: 1.4.8 CVE: CVE-2022-29970 GHSA: GHSA-qp49-3pvw-x4m5 Criticality: High URL: https://github.com/sinatra/sinatra/pull/1683 Title: sinatra does not validate expanded path matches Solution: upgrade to '>= 2.2.0'
Name: sinatra Version: 1.4.8 CVE: CVE-2022-45442 GHSA: GHSA-2x8x-jmrp-phxw Criticality: High URL: https://github.com/sinatra/sinatra/security/advisories/GHSA-2x8x-jmrp-phxw Title: Sinatra vulnerable to Reflected File Download attack Solution: upgrade to '~> 2.2.3', '>= 3.0.4'

Create _config.yml and modify the following contents to suit:

Shell
author: Sally Smith
compress_html:
  blanklines: false
  clippings: all
  comments: [""]
  endings: all
  ignore:
    envs: [development]
  profile: false
  startings: [html, head, body]
domain: supersally.com
exclude:  # Wildcards are not supported yet https://github.com/jekyll/jekyll-watch/pull/93
  - _bin
  - .git
  - .github
  - .gitignore
  - .jekyll-cache
  - .jekyll-metadata
  - .ruby-version
  - .vscode
  - BingSiteAuth.xml
  - Gemfile
  - Gemfile.lock
  - README.md
  - script
email: sally@supersally.com
exclude: [vendor]
jekyll_admin:
  hidden_links:
#    - posts
#    - pages
#    - staticfiles
#    - datafiles
#    - configuration
#   homepage: "pages"
kramdown:
  hard_wrap: false
  line_width: 120
liquid:
  error_mode: strict
  # strict_filters: true
  # strict_variables: true
markdown: kramdown
permalink: /blog/:year/:month/:day/:title:output_ext
plugins:
  - html-proofer,
  - jekyll,
  - jekyll-admin,
  - jekyll-assets,
  - jekyll-docs,
  - jekyll-environment-variables
  - jekyll-feed
  - jekyll-redirect-from
  - jekyll-sitemap
  - jekyll-youtube
  - kramdown
sass:
  style: compressed
title: Journal of Sally Smith, Superwoman
url: https://www.supersally.com

I learned the hard way that the hidden directory .jekyll-cache/ is created when Jekyll runs. It might contain environment variables, including your authentication keys and tokens for all your online services!!!!

Add this directory to .gitignore:

Shell
$ echo .jekyll-cache/ >> .gitignore

Running Jekyll

Below is how you can obtain the most current Jekyll documentation. Read it!

Shell
$ bundle exec jekyll docs

For most operating systems, you can run Jekyll this way:

Shell
$ bundle exec jekyll serve

Read about how Bash does not yet support watched directories in NTFS volumes properly. To compensate, use the --force_polling option:

Shell
$ bundle exec jekyll serve --force_polling

The jekyll command has more options, and you probably want to use them. Use the --drafts option to preview draft articles in the _drafts directory. If you stored your Jekyll website on an NTFS volume, type:

Shell
$ bundle exec jekyll serve --force_polling --drafts

For all other types of volumes:

Shell
$ bundle exec jekyll serve --drafts

Visual Blog Editor

Several Jekyll content 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.

Enable the "side-by-side" editor/preview feature as shown above.

I use Visual Studio Code to edit the content for this Jekyll website, and I preview the live site locally as I work. The next article, Publishing a Draft Article in a Jekyll Collection, describes how to do that.



* indicates a required field.

Please select the following to receive Mike Slinn’s newsletter:

You can unsubscribe at any time by clicking the link in the footer of emails.

Mike Slinn uses Mailchimp as his marketing platform. By clicking below to subscribe, you acknowledge that your information will be transferred to Mailchimp for processing. Learn more about Mailchimp’s privacy practices.