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:

Gemfile

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:

_config.yml

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.

Share to X, Hacker News, LinkedIn.