Setting Up Jekyll with Ubuntu or WSL

Published 2017-01-08. Last modified 2022-05-09.
Time to read: 1 minutes.

This page is part of the jekyll collection, categorized under Git, Jekyll, Scripting, Ubuntu, WSL.

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 followed previously.

Make a Gemfile with the following contents:

Gemfile

source "https://rubygems.org"

gem 'jekyll'
gem "sprockets"
gem 'webrick'

group :jekyll_plugins do
  gem 'jekyll-admin'
  gem '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

gem 'debase', "0.2.5.beta2", require: false
gem 'debase-ruby_core_source', '~> 0.10.15', require: false
gem 'ruby-debug-ide', require: false

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 blog posts 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.