What the heck is Jekyll?
Jekyll is a static site generator (SSG), or a program that takes static files and generates a static website from them. By “static” we mean that the server doesn’t make multiple requests back and forth to either generate the content or to update it as the user interacts with it. In contrast, a dynamic website is one that must communicate with the server constantly either before or during user interaction to build the website. As Eduardo Bouças explains:
[I]magine for a second that the only way for people to know what's happening in the world is to go to the nearby news kiosk and ask to read the latest news. [...]
The attendant has no way to know what the latest news [is], so he passes the request on to a back room full of telephone operators — picture a big telephone switchboard room in the 1950s. When an operator becomes available, they will take the request and phone a long list of news agencies, ask for the latest news and then write the results as bullet points on a piece of paper.
The operator will then pass his rough notes on to a scribbler who will write the final copy to a nice sheet of paper, arrange them in a certain layout and add a few bits and pieces such as the kiosk branding and contact information. Finally, the attendant takes the finished paper and serves it to the happy customer. The entire process will then be repeated for every person that arrives at the kiosk.
Of course this is a vast oversimplification, but a useful one. Your basic content management system (CMS) - WordPress, Drupal, etc - functions exactly like this. For a website that doesn’t need dynamic content this process is ridiculously inefficient, but it’s a process that thousands of people use even when there’s a better solution.
Now, before you get out your pitchforks and start forming up on the far side of the moat, I’m a diehard WordPress fan and I use it on many of my client sites, particularly if the client will be doing the content management. WordPress is second-to-none in my book for user-friendliness, stability, and security (if you keep it updated and minimize your plugin installations, but that’s another post). That doesn’t mean it’s the best solution in all cases, and knowing what tools you need to do a job is vital to success.
Why (or why not) a static site generator
By reducing complexity and reliance on the server to perform requests, static sites vastly increase speed, up to 6 times faster than dynamically created websites. This means that static websites can potentially scale more easily than dynamic websites, especially for those who can’t afford or don’t want to setup server scaling through their hosting provider. Content can be written in markdown, HTML, or even other languages depending on what SSG you choose. Finally, for developers or fans of the command line, all operations can be performed from the command line, making automation on just about any platform a breeze.
Of course, with these advantages come downsides, probably most importantly a lack of server-side real-time data (like trends or recent activity) and an administration interface. Granted if you’re building a static site, you’ve likely decided that dynamic content isn’t needed so a lack of real-time data might not be a disadvantage. One thing that might be important to website administrators is a lack of any user input at all, such as commenting or even search. There are workarounds depending on what static generator you use, but user input kind of goes against the idea of static site generation. Probably the biggest roadblock to using a SSG, at least for non-technical people, is that there is no graphical user interface (GUI) for performing administrative tasks or even for writing content. There are solutions to integrate a SSG into a content management system (CMS) however, if that’s important to you.
So now that we’ve gotten the “what” and “why” out of they way, let’s move on to the “how”.
How to setup Jekyll
Now that’s out of the way, let’s get down to setting up Jekyll, the SSG I chose to use for my freelance website. Jekyll takes raw content files, runs them through a converter, runs that converted content through a Liquid renderer, and then presents you with a static website that’s ready to publish to nearly any web server. It’s also open source, and integrates tightly with GitHub Pages.
First, you need to ensure your system has the following:
The supported operating systems are GNU/Linux, Unix, or macOS, but Jekyll can be run on Windows; it’s how I run it. If you want to run it on Windows, follow this handy guide which worked a treat for me.
After everything’s setup, you should be able to install Jekyll with a few simple commands:
# Install Jekyll and Bundler gems through RubyGems
~ $ gem install jekyll bundler
# Create a new Jekyll site at ./myblog
~ $ jekyll new myblog
# Change into your new directory
~ $ cd myblog
# Build the site on the preview server
~/myblog $ bundle exec jekyll serve
# Or if you don't have/need Bundles
~/myblog $ jekyll serve
# Now browse to http://localhost:4000
Running the serve command creates a local web server to load your website for development purposes.
In the default mode, serve will watch for changes to most files in your directory and update on reload.
Configuration files such as _config.yml (more about this file below) do not update while the Jekyll server is running, so you must restart the server to see changes to those files.
Update Jekyll
If you need to update Jekyll (like if you started this or another tutorial before and got distracted), use this command:
$ gem update jekyll
Basic configuration
The default theme installed with Jekyll is Minima, a very minimal and elegant theme that has a focus on reading. You can see examples of many other Jekyll themes here or here, or search through the RubyGem database directly. I’m not going into how to create your own theme in this post though.
Once you’ve got your theme installed, you want to update the site information.
This is done via a YAML configuration file called _config.yml.
IMPORTANT NOTE: _config.yml does not update while the Jekyll server is running.
You must restart the Jekyll server to see changes to this file in your browser.
Here’s the default _config.yml for a new Jekyll installation:
# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole blog, values
# which you are expected to set up once and rarely edit after that. If you find
# yourself editing this file very often, consider using Jekyll's data files
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
# Site settings
# These are used to personalize your new site. If you look in the HTML files,
# you will see them accessed via Smokie Lee, hello@smokielee.com, and so on.
# You can create any custom variable you would like, and they will be accessible
# in the templates via .
title: Your awesome title
email: your-email@example.com
description: > # this means to ignore newlines until "baseurl:"
Write an awesome description for your new site here. You can edit this
line in _config.yml. It will appear in your document head meta (for
Google search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username: jekyllrb
github_username: jekyll
# Build settings
markdown: kramdown
theme: minima
gems:
- jekyll-feed
# Exclude from processing.
# The following items will not be processed, by default. Create a custom list
# to override the default setting.
# exclude:
# - Gemfile
# - Gemfile.lock
# - node_modules
# - vendor/bundle/
# - vendor/cache/
# - vendor/gems/
# - vendor/ruby/
As you can see, it’s well commented and the options are pretty clear for even beginners. There are lots of global options that can be included in this file; visit the official documentation for more details.
Now that the configuration is out of the way, we can get right down to writing a post.
Writing content
Probably my favorite feature of Jekyll (and many SSGs) is the support for writing posts in Markdown. Markdown is like a shorthand plain text that can be rendered into rich text. Markdown also supports HTML tags, so if there isn’t a Markdown shortcut for it you can write a tag. Jekyll takes the Markdown file and runs it through a converter to create an HTML file during the build process.
Writing a post in Jekyll is simple:
1) Create a new file in the _posts folder named YEAR-MONTH-DAY-title.MARKUP
This naming convention is mandatory, and if your posts aren’t named this way Jekyll will skip them when serving/building your site.
The title part can be whatever you like, but be sure to follow best practices for SEO-friendly URLs.
MARKUP refers to the type of markup that your post is written in.
Jekyll supports Markdown and HTML out of the box, and you can install plugins for nearly any other format you like.
2) Add YAML Front Matter to the top of the file.
YAML Front Matter is the metadata that you stick at the top of your file between two sets of triple dashes (“---”).
This basically says to Jekyll, “This is a post,” and it reads the front matter and processes the variables within it based on your Jekyll configuration.
Here’s a basic example of YAML Front Matter for a post:
---
layout: post
title: Hello World
---
This tells Jekyll that this is a post, the layout it should display in is the “post” layout, and the title is “Hello World.” The triple dashes are the only required front matter elements in a default Jekyll installation; if title isn’t specified Jekyll determines the title from the name of the file.
3) Add your post content.
Now just add your post content in whatever format you saved the file!
You can reference the Jekyll front matter in the content of the post using {{ page.VARIABLENAME }}, or even global variables.
When you’re done writing, save your file and run jekyll serve from a command line to preview your post.
Publishing
When you’re ready to publish your website, Jekyll makes it easy.
Run bundle exec jekyll build or jekyll build and your website will be generated in the _site folder, ready to upload to the web server of your choice.
Jekyll also works out of the box with GitHub Pages, making it a perfect platform for building free websites based on GitHub repos.
Conclusion
And that’s it for setting up a basic Jekyll site! If you found this helpful, please share it so that others can benefit from it too. If I screwed something up, please let me know.
Next time, I’ll try to write a post about how to roll your own Jekyll theme, or maybe adding your own logic to the mix.