Jekyll
By Ben of OpenClipart, CC0

In the previous post, we discussed setting up a dev environment consisting of the Windows Subsystem for Linux and Visual Studio Code. This post will focus on building a Jekyll website from scratch in this environment.

Installing Jekyll

According to the documentation, there are a number of dependencies to install: gcc, make, and ruby.

To install gcc and make, the built-in package handling utility called apt-get can be used to download the build-essential package, which includes gcc and make.

> sudo apt-get update # Updates all installed packages to the latest version
> sudo apt-get install build-essential

Next, Ruby will need to be installed, since Jekyll is written in that language. It turns out that Ruby actually comes installed by default, but as of the Creator’s Update for Windows 10, installing Jekyll fails due to some permissions error. This can be worked around by using the Ruby Version Manager, aka rvm, to install ruby.

> \curl -L https://get.rvm.io | bash -s stable # Installs RVM
> source /home/<username>/.rvm/scripts/rvm # Substitute <username> for the actual username
> rvm list known # Lists known versions of Ruby
> rvm install ruby-<version> # Substitute <version> for the actual version, eg 2.4

The 2nd line must be run in every shell session in which ruby will be run. I recommend appending it to the .bashrc file (/home/<username>/.bashrc), which is run every time a new shell is launched.

For the third line, the version of Ruby must be greater than or equal to 2.0. I installed 2.4, which has been sufficient for me so far. Versions 1.9 and newer of Ruby come with “RubyGems” which is the last requirement detailed in the documentation.

Finally, we can install Jekyll using RubyGems, which is Ruby’s package manager, where a gem is a package. At this point, I would also recommend installing the bundler gem, used for managing other gems and their respective versions for individual projects and pretty much required if the website will be published to GitHub Pages. Furthermore, Jekyll plugins are conveniently gems, so bundler can be used to manage those as well.

> gem install jekyll bundler

A starter Jekyll project

There are lots of ways to get started with Jekyll, but I recommend starting pretty much from scratch in order to develop a better understanding of the fundamentals of the Jekyll framework and then building on that base from there.

Fortunately, Jekyll provides a built-in way to start with a skeleton, assuming bundler is installed:

> jekyll new /path/to/project # can just be "." for the current directory

That command provides the following file structure:

Running the following command will feed these files to Jekyll which will in turn spit out the HTML and CSS website in the _site/ directory:

> jekyll build

Running the next command will build and then host the generated website at the address “localhost:4000”, which is viewable in a browser:

> jekyll serve

To get rid of the theme entirely, delete the about page, and delete the lines that contain a reference to the “minima” theme in the Gemfile and _config.yml. Update Gemfile.lock to get rid of the minima gem by running:

> bundle update

A great example of a more fleshed out skeleton is Jekyll Now. It contains additional directories that are explained upon in the next section.

The directory structure

For most websites generated by Jekyll, their corresponding projects will have the corresponding structure, similar to what’s laid out in the documentation:

  • _posts/
  • _drafts/
  • _site/
  • _includes/ - contains partial HTML files that can be included by other html files, eg analytics, headers, footers, etc.
  • _layouts/ - contains HTML files that serve as templates for individual pages, eg post.html, default.html, guide.html
  • _sass/ - contains any partial SASS/SCSS files, which is natively supported by Jekyll
  • _data/ - contains any static, “well-formatted site data” such as csv or json files
  • assets/ - recommended to contain the main css/scss/sass file, images, and JavaScript files
  • files/ - recommended to contain individual pages such as the about page or a 404 page
  • _config.yml
  • index.md or index.html
  • Gemfile
  • Gemfile.lock

Common Jekyll plugins

Jekyll sports an extensive plugin system. The three most common (and most useful, in my opinion) plugins for blogs are:

There are lots of other fantastic plugins out there, but note that if the website will be hosted on and generated by GitHub Pages, then the project will only be able to use a subset of approved plugins.

Further reading

One great aspect of using Jekyll over other static site generators is that the community around it is pretty active, resulting in lots of guides and helpful reads all over the web. Here is a short list of ones that helped me a lot when I got started.

For reference, I plan on writing a future post detailing miscellaneous Jekyll tips and tricks such as implementing site-wide search and SEO tags.

Tags: jekyll windows bash wsl