Learn Enough CSS & Layout to Be Dangerous | Learn Enough to Be Dangerous
You have to make a choice. Choose...wisely.

Get occasional notifications about things like product discounts, blog posts, and new or updated tutorials. Unsubscribe at any time.

Quick Checkout
or Pay by Credit Card
Error processing your payment
  • You didn't choose whether or not to be added to the mailing list
Confirm
$0.00

Payments and credit card details are securely managed and protected by Learn Enough's payment processor, Stripe. More information on their site:

CART
Total
$0.00

Your Cart is Empty

$30
$300
$300
$XY
$XY
1234
Get Single Tutorial
MORE INFO

Learn Enough CSS & Layout to Be Dangerous is available as an ebook, an offline video series, and as a structured, self-paced online course. The course includes full online access to the book content, streaming videos, progress tracking, exercises, and community exercise answers.

All Access Subscription
MORE INFO

The Learn Enough All Access Subscription includes the entire Learn Enough introductory sequence and the full Ruby on Rails Tutorial. More than 2500 pages of book content and 53 hours of video that teach you to code from total beginner up to professional-grade web development.

Sign up for the course and get access to the full tutorial and streaming screencasts!

5.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 (Figure 5.2), a free and open-source program for generating static websites (that is, sites that don’t change from visit to visit).1

images/figures/jekyll
Figure 5.2: Not Jekyll and Hyde… rather, Jekyll the static site generator!

By learning Jekyll, you’ll develop 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). 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.2

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 Learn Enough Text Editor 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 thousands 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:3

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.

5.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 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 self-contained Ruby packages known as gems. We can install Bundler using the gem command, which comes for free with Ruby:

$ gem install bundler -v 2.2.17

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 5.1.

Listing 5.1: Adding the Jekyll gem. Gemfile
source 'https://rubygems.org'

gem 'jekyll', '4.2.1'

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.2.17_ install

Although Jekyll is designed to work with a system of templates (Section 5.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.2.17_ 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 5.1). The result should look something like Figure 5.3.

images/figures/localhost
Figure 5.3: No more URL pointing to a file—you’re running on a server now!
Box 5.1. Server ports

If you look at the URL for the Jekyll site, you’ll notice that the URL ends in “:4000”. That is the server port. If you end a URL with a colon followed by a number you are telling the browser to connect to that port on the server… so what does that mean?

You can think of server ports as being like individual phone numbers for different services that run on a computer. The default port number for the World Wide Web is port 80, so http://www.learnenough.com:80 is the same thing as http://www.learnenough.com, while the default port for a secure connection is 443, so https://learnenough.com:443 is the same thing as https://learnenough.com (with https in place of http). Other common port numbers include 21 (ftp), 22 (ssh), and 23 (telnet).

In the context of developing applications on a development machine, using port numbers allows us to solve the important problem of being able to run two or more apps simultaneously. Suppose, for example, that we wanted to run two different Jekyll websites on our development server. By default, both of them would be located at localhost:4000, but this would cause a conflict because the browser would have no way of knowing which site to serve when visiting that address. The solution is to add an extra piece of information, the port number, which allows the computer to distinguish between, say, app #1 running on localhost:4000 and app #2 running on localhost:4001.

As noted above, Jekyll’s default server port is 4000, but we can set a different port number using the --port command-line option as follows:

  $ bundle _2.2.17_ exec jekyll serve --port 4001

To connect to this second server, we would then type localhost:4001 into our browser’s address bar.

If you’re using the cloud IDE suggested in Learn Enough Dev Environment to Be Dangerous, you’ll have to pass options for the port number (Box 5.1) and host IP number when running the jekyll command:

$ bundle _2.2.17_ 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 5.4. The result, apart from the browser URL, should be the same as for the local system shown in Figure 5.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.)

images/figures/cloud_share
Figure 5.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 that 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 5.5).4

images/figures/darth
Figure 5.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"

5.2.2 Exercises

  1. Try starting Jekyll up on a non-standard port like 1234.

Join the Mailing List

Get occasional notifications about things like product discounts, blog posts, and new or updated tutorials. Unsubscribe at any time.