Create a Static Site with Jekyll
An Overview of Setup and File Structure
Getting Started
As a static site generator, Jekyll gives us the ability to take text written in a markup language and insert that content into pre-defined layouts to be displayed in a browser. This is great for simple sites that don’t require a backend or database.
Jekyll is written in Ruby, so it does require the installation of Ruby before getting started. You’ll also want to install the Jekyll gems by entering the following command in the terminal while in your projects directory.
gem install jekyll bundlerStarting a new project is as easy as typing ‘jekyll new’ followed by the name of your project/site. Once you navigate into the newly created project’s directory, run the following command to access the site on localhost:4000.
bundle exec jekyll serve --livereloadIncluding the live reload tag, allows hot reloading which means that you don’t have to refresh the page to see recent changes appear.
The first time that you run the serve command, a _site directory will be created at the root of your project. This will contain the build files for your site. You’ll also need an index.html file with markup for your home page.
Supported Languages
As mentioned before, Jekyll accepts markup languages such as HTML. Another language that you’ll need to be familiar with is a templating language called Liquid. The 3 key components to Liquid are objects, tags, and filters.
Objects output pre-defined variables by wrapping the variable name in double curly braces. These variables could be defined in the front matter which we’ll talk about shortly.
Tags contain logic for templates like if statements or iteration. They are wrapped in percentage signs with curly braces on the outside. If you have used Ruby before, tags may remind you of the syntax used in HTML.ERB files.
Filters are used to transform objects. They are wrapped in double curly braces with the object on the left of a | and the filter on the right. Here’s an example from the Jekyll docs that shows how to capitalize a word with a filter.
{{"hello" | capitalize}}You can find a full list of filters available here.
Front Matter
To signal Jekyll that we need to process some written Liquid, we need to add something called front matter to the top of the file. Front matter is written in YAML and sits between three dashes above and below it. Inside of those dashes, we can define variables for the markup file or define layouts.
We don’t have to have anything defined in the front matter at all. If we have the two lines of three dashes at the top, any Liquid within that file will still be processed.
Here’s an example of front matter that defines a layout and some variables that are being called with Liquid objects in the code below.
---
layout: default
hero-heading: Chicago Parks
hero-content: View the Chicago Park Districts Locations and Events
---<div class="hero-content"> <h1>{{ page.hero-heading }}</h1> <p>{{ page.hero-content }}</p></div>
We can call on the variables created in the front matter by using the prefix page followed by dot notation.
Layouts
We can define layouts in a directory labeled _layouts. Layouts can be written in HTML and use Liquid to specify content that is to be included. The content object is used to define where page content should be located within the layout.
{{ content }}All markup files that need to be persisted on each page of the site can be kept in an _includes directory. This could be things like a header, footer, or navigation menu for example. Once those files are defined, we can use them in our layouts by adding an include tag with the name of the file like this:
{% include header.html %}Links to style sheets can be included in the header of a layout. It’s important to maintain the proper file structure so that your CSS, JavaScript, and other assets are accessible. All assets are kept in a folder called assets with a subfolder for storing CSS, images, JavaScript, and whatever else is needed.
Posts
Static sites are frequently used as a space for blog posts. As you can probably imagine, the markup files for posts will need to live inside of a _posts directory.
Posts can only be written as a text file and follow this specific format: the publish date, then a title, extension. These can be iterated through to be displayed on a page. To access the posts, you can use a Liquid object titled site.posts.
Collections and Data
Collections are similar to posts, but they don’t have to be grouped by date. They are sort of like arrays and can be defined through mapping. You can set up a collection within a _config.yml file at the root of your directory. Here’s an example of what one might look like:
collections:
tutorials:
sort_by: lessonNote that indention is important here because we are creating something like a hashmap. As you can see we can sort the tutorials collection by key values from front matter as well.
If there is a set of data that you’ll need for a specific page, you can define that data in a markup file inside a _data directory. This can be called on by using the Liquid object site.data.file-name-here.
Final Words
In closing, I want to mention that you can easily deploy your static site on GitHub pages. Another great option for deployment is Netlify which will supply a preview to your pull requests within the GitHub repo. Netlify also offers its own CMS for quick changes to content.
As always, I’ll leave you with some additional documentation and material to continue learning. Check out the Jekyll docs and resources below to dive in deeper.
