Make a Static Website with Jekyll

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.

Prerequisites

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.

Goals

Learn what a static site generator is

Install Jekyll

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.

At this point, all the setup is complete. In your project directory, run the following code:

jekyll serve

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.

Configuration

In the main directory, there's a file called _config.yml. It looks like this:

# Site settingstitle: Your awesome title
email: your-email@domain.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:'http://yourdomain.com'# the base hostname & protocol for your sitetwitter_username: jekyllrb
github_username: jekyll
# Build settingsmarkdown: kramdown

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

_includes

In Jekyll, _includes are files that should show up on every page - header, footer, etc.

default.html

page.html

---
layout: default
---
<h2>{{ page.title }}</h2>
{{ content }}

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.

Pushing Jekyll site to GitHub pages

Create an empty repository in GitHub. Mine is startjekyll, so the Git repo URL is https://github.com/taniarascia/startjekyll.

There is one change that needs to be made in order to have one site for both your local Jekyll and the live GitHub pages.

Duplicate your _config.yml and call it _config_dev.yml.

Leave the _config_dev.yml as is, and change _config.yml for the live site.

baseurl:"/startjekyll"url:"https://taniarascia.github.io"

Now, when you want to work on the site locally, you will run the following command:

jekyll serve --config _config.yml,_config_dev.yml

And it will load the information from the dev config.

Serve your Jekyll one last time to ensure all the final changes have been updated. Here are the commands to push the site to GitHub pages:

git remote add origin https://github.com/taniarascia/startjekyll.git

Add the GitHub repository.

git checkout -b gh-pages

Ensures that you're on the gh-pages branch, not master.

gitadd.

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.

Join the newsletter

I write about JavaScript, programming, and front-end design. Join over 6,000 other developers in keeping up with my content. Unsubscribe whenever. Never any spam, ads, or affiliate links.

I'm Tania, a full-stack software developer specializing in modern JavaScript. I make
open source coding projects and write free, quality articles and tutorials that help
thousands of people daily. No ads, no sponsored posts, no bullshit.