This chapter is from the book
This chapter is from the book
This chapter is from the book
9.2 Jekyll
When building a professional-grade website, it’s essential to use a system capable of supporting templates to eliminate duplication. To accomplish this, we’ll be using Jekyll (https://jekyllrb.com/) (Figure 9.21), a free and open-source program for generating static websites (that is, sites that don’t change from visit to visit).2
)
Figure 9.2: Not Jekyll and Hyde… rather, Jekyll the static site generator! (Poster image courtesy of BFA/Alamy Stock Photo.)
By learning Jekyll, you’ll cultivate the skills needed to develop and deploy a real website—skills that are transferable to other static site generators (such as Middleman and Hugo) and to full-blown web frameworks (like Ruby on Rails (https://www.railstutorial.org/)). Learning the template language used by Jekyll (called Liquid) is also a valuable skill in itself, as Liquid is widely used in systems like the Shopify ecommerce platform.3
In addition to supporting templates, Jekyll also includes a bunch of other useful features:
Write content in Markdown (the lightweight markup format we first discussed in Chapter 6 of Learn Enough Developer Tools to Be Dangerous) in your text editor of choice.
Write and preview your content on your site locally in your dev environment.
Publish changes via Git (which also gives you an automatic off-site backup).
Host your site for free on GitHub Pages.
No database management.
Originally developed by GitHub cofounder Tom Preston-Werner, Jekyll is used by millions of people around the world and is an industrial-strength tool for creating static websites. For example, the fundraising platform for U.S. President Barack Obama’s 2012 reelection campaign, which handled 81,548,259 pageviews and raised over $250 million, was built using Jekyll:
By using Jekyll, we managed to avoid the complexity that comes with most CMSes (databases, server configuration) and instead were able to focus on things like optimizing the UI and providing a better user experience. To work in this environment, the most a front-end engineer had to learn was the Liquid template language that Jekyll uses, and boy is that simple.4
9.2.1 Installing and Running Jekyll
Jekyll is written in the Ruby programming language, and is distributed as a Ruby gem, or self-contained package of Ruby code. As a result, installing Jekyll is easy once you have a properly configured Ruby development environment.
If your system is not already configured as a dev environment, you should consult Learn Enough Dev Environment to Be Dangerous (https://www.learnenough.com/dev-environment) at this time. This step might prove challenging, especially if you decide to configure your native system, but in the long run the effort is well worth the reward.
Once you’ve got a working dev environment, you can install Jekyll using Bundler, a manager for Ruby gems. We can install Bundler using the gem command, which comes with Ruby:
$ gem install bundler -v 2.3.14
Next, we need to create a so-called Gemfile to specify the Jekyll gem:
$ touch Gemfile
Then use a text editor to fill the Gemfile with the contents shown in Listing 9.1.
Listing 9.1: Adding the Jekyll gem.
Gemfile
source 'https://rubygems.org' gem 'jekyll', '4.2.2' gem 'webrick', '1.7.0'
If you run into any trouble, check the Gemfile at https://github.com/mhartl/mhartl.github.io to see if it has been updated.
Finally, we can install the jekyll gem using bundle install (with a little extra code to ensure that we’re using the right version of Bundler):
$ bundle _2.3.14_ install
Although Jekyll is designed to work with a system of templates (Section 9.3), in fact it can work with a single file, such as our current index.html. To see how it works, we can run the Jekyll server in our project directory (using bundle exec to ensure that the right version of Jekyll gets run):
$ bundle _2.3.14_ exec jekyll serve
If you’re working on a native system or a virtual machine (as opposed to a cloud IDE), at this point the Jekyll app should be available at the URL http://localhost:4000, where localhost is the address of the local computer and 4000 is the port number (Box 9.1). The result should look something like Figure 9.3.
)
Figure 9.3: No more URL pointing to a file—you’re running on a server now!
If you’re using the cloud IDE (https://www.learnenough.com/dev-environment-tutorial#sec-cloud_ide) suggested in Learn Enough Dev Environment to Be Dangerous, you’ll have to pass options for the port number (Box 9.1) and host IP number when running the jekyll command:
$ bundle _2.3.14_ exec jekyll serve --port $PORT --host $IP
Here $PORT and $IP should be typed in literally; they are environment variables provided by the cloud IDE to make the development site accessible on an external URL. Once the server is running, you can visit it by selecting Share and then clicking on the server URL, as shown in Figure 9.4. The result, apart from the browser URL, should be the same as for the local system shown in Figure 9.3. (For simplicity, in what follows we sometimes refer to localhost:4000, but users of the cloud IDE should use their personal URL instead. Mutatis mutandis.)
)
Figure 9.4: Sharing the URL on the cloud IDE.
After starting the Jekyll server, you should find a new folder in your project called _site (with a leading underscore):
$ ls _site index.html
This folder contains the output from the Jekyll server as it builds your site from the source files (currently just index.html).
The _site directory and all its contents are generated by Jekyll every time a file is saved, and if you were to make any changes in the _site folder, they will be automatically overwritten. As a result, you should never make changes in any of the _site files themselves—they would only be overwritten by Jekyll. There’s nothing more frustrating than accidentally working on updates in an automatically generated folder, only to have your changes overwritten by an uncaring static site generator (Figure 9.5).5
)
Figure 9.5: TFW changes accidentally made in generated files get overwritten.
Because all its content is generated by Jekyll, it’s a good idea to ignore the _site directory by adding it to your .gitignore file, and there’s a Bundler configuration directory called .bundle that should also be ignored:
$ echo _site/ >> .gitignore $ echo .bundle >> .gitignore $ git add .gitignore $ git commit -m "Ignore the generated site and Bundler directories"
You should also add the Gemfile (and the associated auto-generated Gemfile.lock file) to the repository:
$ git add -A $ git commit -m "Add a Gemfile"
9.2.2 Exercises
Try starting Jekyll on a non-standard port like 1234.