A tutorial on how to install Jekyll (the static site generator) and create a simple theme for blog posts and regular pages. Written on a macOS environment.
Jekyll is a static site generator that runs on the Ruby programming language. You may have heard of Jekyll or static site generators, but don’t know how or where to get started. This guide is intended to be a complete tutorial, and require no additional resources to get you up and running with Jekyll.
While Jekyll is advertised as a blogging platform, it can be used for static websites as well, much like WordPress. Jekyll harnesses the power of markdown, which makes writing HTML much easier and more efficient. Additionally, Jekyll has Sass built in, and if you’ve never used a CSS preprocessor, it’s a great time to learn. If you already know how to use Sass, you’ll feel right at home.
If you don’t have a basic knowledge of command lines and Git, please read the getting started with Git article. This will cover everything you need to know to get started with using Git and the command line.
Learn what a static site generator is
Create a custom website running on Jekyll and Sass
Deploy a Jekyll site to GitHub pages
Additionally, this tutorial is currently Mac only. If I get a request to do a Windows tutorial, I’ll look into it, but until then, you must be running OSX for this tutorial to be effective.
What is a static site generator?
A static site generator builds a website using plain HTML files. When a user visits a website created by a static site generator, it is loaded no differently than if you had created a website with plain HTML. By contrast, a dynamic site running on a server side language, such as PHP, must be built every time a user visits the site.
You can treat a static site generator as a very simple sort of CMS (content management system). Instead of having to include your entire header and footer on every page, for example, you can create a header.html and footer.html and load them into each page. Instead of having to write in HTML, you can write in Markdown, which is much faster and more efficient.
Here are some of the main advantages of static site generators over dynamic sites:
Speed – your website will perform much faster, as the server does not need to parse any content. It only needs to read plain HTML.
Security – your website will be much less vulnerable to attacks, since there is nothing that can be exploited server side.
Simplicity – there are no databases or programming languages to deal with. A simple knowledge of HTML and CSS is enough.
Flexibility – you know exactly how your site works, as you made it from scratch.
Of course, dynamic sites have their advantages as well. The addition of an admin panel makes for ease of updating, especially for those who are not tech-savvy. Generally, a static site generator would not be the best idea for making a CMS for a client. Static site generators also don’t have the possibility of updating with real time content. It’s important to understand how both work to know what would work best for your particular project.
We’re going to install Jekyll locally before deploying anything to GitHub pages.
Install Command Line Tools
Open Terminal. Check to see if you have XCode Command Line Tools installed by typing gcc -v. At this point, it will prompt you to install if you don’t. Or run this code to install:
Ruby should come pre-installed on all OSX computers. You can check if Ruby is installed by running ruby -v. It should return with Ruby version 2.0.0 or higher.
If for some reason you’re running a lower version, you can update.
sudo gem install ruby
If you plan on using Ruby for more purposes, it might be advisable to install Ruby Version Manager. Otherwise, the above commands are perfectly fine.
Bundler is a package manager that will aid you in installing all the Jekyll dependencies.
sudo gem install bundler
Successfully installed bundler-1.10.6
Parsing documentation for bundler-1.10.6
1 gem installed
Create a directory, and add a file called Gemfile. The file doesn’t contain an extension. Type the following contents into the file and save it.
In Terminal, run this command in the directory that contains the Gemfile:
This command should run for a while. It might ask you for your sudo password, or for you to run sudo bundle install. When it’s finished, it will say something like this:
Bundle complete! 1 Gemfile dependency, 55 gems now installed.
Great! Now that that’s finished, you can successfully install Jekyll. I’m going to call my project startjekyll
jekyll new startjekyll
New jekyll site installed in /Users/tania/Sites/startjekyll.
Move to the new directory.
And initialize a new Git repository.
Initialized empty Git repository in /Users/tania/Sites/startjekyll/.git/
At this point, all the setup is complete. In your project directory, run the following code:
This command runs a “watch” on the entire server. Changes made to any files (except the configuration file!) will be compiled into static HTML.
Now go to the url http://localhost:4000. You will see this page.
Congratulations, you’ve just installed Jekyll! If you type CTRL + C in Terminal, it will end the running process and the site will no longer be served to localhost. Simply run jekyll serve again and it will come back up.
Creating a Jekyll theme
With Jekyll, we’ll be able to process SCSS (Sass) files into CSS (.scss -> .css), and Markdown into HTML (.md -> .html). No additional task runners or Terminal commands are required!
There are a few important things to know about the Jekyll file system.
The “distribution” folder is called _site. This is what the static site generator generates! Never place any files in that folder; they will be deleted and overwritten.
The _sass folder is for Sass partials. Every file in here should begin with an underscore, and it will compile into the css folder.
Any file or folder placed into the main directory will compile into the _site directory as-is.
There is more to know, but we’ll learn along the way.
I’m going to go through all the files from here on out. If you’d rather clone the Git repository, you can view it here. All the files in the repo will be the same as what I display here.
In the main directory, there’s a file called _config.yml. It looks like this:
# Site settings
title: Your awesome title
email: [email protected]
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: "http://yourdomain.com" # the base hostname & protocol for your site
# Build settings
Pretty obvious. There are two important things to know about the config file:
Changes made to _config.yml will not be watched by jekyll serve. You must restart and reserve Jekyll after any config changes.
All indentation is mandatory and must be made with two spaces, or else the file will not work.
I’m going to make a few changes to the configuration.
# Site Settings
title: Start Jekyll
email: [email protected]
A guide to getting started with Jekyll.
# Build Settings
I changed the base URL to http://localhost:4000. This will be for the dev configuration. I’m declaring _sass as the sass directory, to ensure the Sass compiles correctly. I’m adding include: ['_pages'] so that custom pages will be organized into their own directory, and input: GFM will allow Github Flavored Markdown.
Customizing your Jekyll Theme
The default styles try to be basic, but they’re still far too stylized for my liking. We’re going to override all the styles and make them much more simple. You can turn off the Jekyll serve at this point and just start saving files. We’ll go from top to bottom alphabetically.
I’m using my own name as an example, but obviously change everything to match you.
In Jekyll, _includes are files that should show up on every page – header, footer, etc.
All the dashes at the top are mandatory. If you don’t include them, the website won’t work properly. For pages and posts, the default layout gets loaded, plus any additional layout information you desire.
Same as the page, but with date and author metadata.
Ensures that you’re on the gh-pages branch, not master.
git add .
Track all files.
git commit -am "Initial commit"
Commit all files.
git push origin gh-pages
Push all files to gh-pages branch.
At this point, you should be able to open up taniarascia.github.io/startjekyll, and it should be your Jekyll project! Without using any external task runners (like Grunt or Gulp), you can now work on the Sass files on your website, and serve up markdown files in place of HTML.
From here, it will be very easy to customize Jekyll to your liking. I purposefully kept every page as simple as possible, using semantic HTML5 tags. I sincerely hope this guide helped get you up and running with Jekyll. I documented all the steps along the way to ensure that the Sass will compile properly, and you won’t have issues being on the right branch to push to GitHub pages.
If you came across any trouble or confusion, please let me know and I’ll improve the tutorial.
I'm Tania, a designer, developer, writer, and former chef from Chicago. I currently work full-time as a web developer, and sometimes I write for DigitalOcean and SitePoint. I love to create things for the web.