The web is a fundamental part of how we communicate and do business today. And having a professional website immediately adds legitimacy to anything you’re saying or selling.
Unfortunately, building and hosting a website can be an expensive and sometimes time consuming task.
That’s where Jekyll comes in, a free tool to build websites that can then be published and deployed for free or for cheap.
Static vs. Dynamic Websites
First, let’s define what it means for a website to be a static site.
A static site only includes content that can be loaded from a file, things like HTML, CSS, JavaScript, and images.
This type of content, which is stored directly and delivered verbatim from a server is called static content.
A static site doesn’t include any dynamic content or things that can change on the fly or be generated by server code. This means that you can’t use server code to render content or pages.
Tools like WordPress, Drupal, Joomla, and Umbraco are called content management systems or CMSs. CMSs like WordPress are a popular choice for building websites and blogs because they make it easy to publish a site without having to build it from scratch.
However, CMSs do have some downsides. Here’s an example regarding how WordPress handles an incoming request and delivers a page to the browser.
First, someone uses their browser to request a page from your website.
The WordPress code running on your server sees that incoming request and looks up the content for that page in a database that’s running on that server or maybe somewhere else.
After retrieving that raw content, the WordPress engine applies templates, injects plugins and other add-ons and performs a number of processing steps on that content, which eventually results in an HTML page that’s pushed back down to the browser.
This works, but it can be slow, especially if the server you’re on isn’t very powerful. Let’s compare that with how a static site works.
With a static site, all the site’s pages and content are pre-built and stored as simple files directly on the web server. When the browser requests a page, the server simply serves those files directly. This makes static sites incredibly fast.
Advantages of Static Sites
Because the server only needs to serve simple files, static sites load incredibly fast.
Fast loading times helps keep your users engaged and can improve your search engine ranking as well. Since you don’t need a powerful or fancy server, static sites are also very cheap to host.
Another advantage of static sites is security. CMSes like WordPress and Drupal are huge targets for hackers and new vulnerabilities are found and exploited on a regular basis.
Unless you regularly update all of your CMS software with every new security patch, your site could be at risk.
Static sites are virtually risk-free because there’s no server code running to exploit. It’s just static files on the file system of the server.
Use Cases for Static Sites
It’s important to understand when a static site makes sense, and when you should use a CMS or a full-blown web application instead.
The static site approach is fantastic for blogs, landing pages, and informational sites.
For example, you can build personal home pages, corporate blogs, resume sites, and promotional landing pages all as static sites.
A good rule of thumb here is if the site only changes when you or another author uploads new content, it’s probably a good fit for a static site. On the other hand, sites where content is rendered dynamically or on the fly, aren’t a good fit.
Neither are sites where users need to authenticate or log in, for example, building a photo-sharing app or a site where users can upload stories wouldn’t be possible as a static site because you need server code running to handle users logging in and updating content in real-time.
Tools for Static Sites
To create a static site, you could write all of the HTML files by hand, but that would be a lot of work.
The easiest way to build a static site is with a tool called a static site generator.
A static site generator lets you write your posts or you pages in a simpler language like Markdown and then automatically generates HTML for you using a template.
Tools like Jekyll, Hexo, and Hugo are some of the most popular static site generators. The website https://staticgen.com has a comprehensive list of static site generator projects.
When it comes to picking a static site generator, you should investigate a few things before you decide on the tool you want to use:
First, what language or markup will you need to write your content in? Most static site generators use Markdown. And if you’re starting from scratch, Markdown is definitely the simplest way to go.
However, if you’re bringing existing content in another format like AsciiDoc, you’ll need to investigate which generators will support your content.
Next, unless you already have a design or a template you’ll use, do some searching to see if there are good themes and templates available.
The top generators like Jekyll and Hugo have hundreds of free high-quality themes contributed by the community. On the other hand, if you’re building a theme yourself or you’re adapting an existing design, look into the templating language that the generator uses.
For example, since Jekyll runs on Ruby, it uses the Liquid language which is also written in Ruby. Hugo, on the other hand, runs on Go and uses Go templates. If you customize or create a theme, you’ll spend some time writing template code. So pick a generator that uses a templating language that you’re comfortable with or you don’t mind learning.
It’s also a good idea to pick a generator that’s popular and has a strong community of users. The amount of stars and open issues that a generator’s repository has on GitHub is a good indicator of how popular it is and how much support there will be for it.
And finally, just play around with a few different tools just to get a feel for their similarities and their differences.
Why Jekyll?
Jekyll is the most popular static site tool on the internet today. There are thousands of websites built with Jekyll every single day.
What makes it so popular? For one Jekyll is powerful and extensible. It’s frequently used to build blogs but it also works great for portfolios, marketing sites and many other types of websites.
Jekyll also has a huge community behind it. The Jekyll community creates themes and templates that you can use for free, plugins to add more advanced features, and a whole lot more.
Jekyll is a good choice if you don’t have a lot of experience with static sites because there are so many templates and plugins available for free.
It’s also built on top of the Ruby language which is a plus if you’re familiar with Ruby, but if you’re not, it can be a little tricky to install.
Installation
The first step is installing Jekyll on your machine. Follow the official instructions on the Jekyll website, at https://jekyllrb.com. There are detailed instructions here for Mac, Linux and Windows.
Because Jekyll is built on top of Ruby, you’ll need to make sure that Ruby is installed first.
You can do this by opening your terminal, or your shell, and typing ruby -v and also gem -v. If you get an error message when you run either of these commands, you’ll need to install Ruby first, before continuing with Jekyll.
Once you’ve installed Jekyll, double-check that it’s working as well, by doing jekyll -v. If you see a version number here too, you’ve installed Jekyll correctly, and you’re ready to go.
If you get an error, retrace the steps in the installation guide to make sure you haven’t missed something.
Creating a Jekyll Site from Scratch
First, create a new Jekyll project. Open up your terminal or your shell, and navigate to the place where you want to store your site files.
Eg. cd .\Documents\, and then run the jekyll new awesome-static-site.
Running jekyll new creates a new folder called awesome-static-site with a bunch of files inside.
Then, run cd awesome-static-site, and then open it up in your favorite text editor or code editor.
By default, Jekyll sets up a blog-style site with a sample post in this _post folder. If you are building a blog, any new post you write will go into this _post folder as well.
This is a good point to initialize a git repository for this project. Switch back into your terminal or shell and run git init to initialize a git repository,
Run git status to check to see what needs to be committed, then run git add --all, followed by git commit -m Create initial project.
If you’re on Windows, there’s one more thing you’ll need to do. Run a command called bundle. Eg. bundle lock --add-platform ruby, and then one more time, bundle lock --add-platform x86_64-linux.
Previewing the Site
Take a look at what the site looks like so far. Since you haven’t added any actual content yet, you’ll just see the default Jekyll theme and some boilerplate text.
To preview the site, you’ll run this command in the terminal: bundle exec jekyll serve.
This starts up the Jekyll preview server and tells you that it’s available on port 4000. Now you can switch into a web browser and type localhost:4000 to see the page.
What you should see is the basic layout and structure of the site. Jekyll built all the site files and is hosting them for you in memory.
This isn’t accessible to anyone else on the internet. This is just on your local machine. If you make changes to the site files while this preview server is running, you can refresh the browser to see the changes immediately.
As an example, if you edit the about.md page and just add something like “Hello world!”, saving this, going back over here to the browser and refreshing to see the changes immediately.
You can use bundle exec jekyll serve command anytime you want to preview the changes that you’re making to the site. When you’re done working on the site, you can switch back into the terminal and press Control + C to stop the preview server. You may need to type y and then Enter to get it to stop.
Theme Installation
Jekyll uses packages called themes to let you easily change the look and feel of your site.
Most themes come with instructions that will tell you how to install the theme in your project. There are two common ways to install Jekyll themes that you’ll come across. Some themes will tell you to fork the theme repository on GitHub and use that as a starting point for your project.
If you pick a theme that uses this method, you won’t start your site using the above guide.
Instead after forking the theme repository, you’ll clone your fork using git clone. And then you’ll build your site using the theme as the starting point.
Other themes give you the option to install the theme as a gem. If you aren’t familiar with the Ruby terminology, a gem is a downloadable package of Ruby code. In this case, downloading a theme gem can be a convenient way to add a theme to your project.
For example: To install the Athena theme, open up the Gemfile in the root directory, find the line that currently has the gem Minima, which is the default theme and replace it:
1
2
3
# This is the default theme for new Jekyll sites. You may change this to anything you like.# gem "minima", "~> 2.0"gem"jekyll-athena"
Also make sure to change the theme in the _config.yml file as well:
Save that and then switch back into the terminal, you’ll run the bundle command. That’ll install the new gem that you specified in the Gemfile, jekyll-athena gem. Run bundle exec jekyll serve to start up the preview server again to see the changes made.
Site Configuration File
Every jekyll project contains a configuration file called _config.yml Here, you can change the title of your site, add your email address, add a description as well, etc.
Later on, when you get ready to publish the site and you have your own domain name, you want to put that as the url property.
If you have a more complex theme installed, it may add more properties to this configuration file.
It’s important to know that if you make changes to config.yml, they won’t be picked up until after your restart the previous server manually. Meaning you’ll have to run bundle exec jekyll serve once more to see changes made.
Most of the time, deployment scripts expect the site files to be in a folder called public. But by default, jekyll creates a folder called _site.
You can alter this by adding destination: public as a property to the _config.yml file.
Afterwards, go to your .gitignore file and add a line for ignoring the folder called public.
This is important because you don’t want to check the build site files into git.
Building a Website
Creating Posts with Jekyll-compose
You can manually create a new file in the _posts folder to create a post, but there’s an even easier way.
First, you’ll need to install a new plugin called jekyll-compose, you can do this easily by adding the following line to the bottom of your Gemfile: gem jekyll-compose', group: [:jekyll_plugins] and then run bundle in your terminal to install it.
With this plugin installed, you can run bundle exec jekyll post in the terminal and then type in your title for the new post, which will then automatically generate a new post file with the corresponding title and date.
The section that has three dashes at the beginning and at the end at the top of the post is called the front-matter section, which we’ll get into next.
1
2
3
4
5
6
7
8
9
10
11
---
layout: post
title: Hello World~
date: 2020-06-20 13:00 -0700
---
Hi there, this is an example of how a post layout looks on a Jekyll Site!
## What else is here?
*More content coming soon...*
Front Matter Content
The section at the top of each post file is called the front matter.
This section stores metadata or properties about the post. You can change or add to these properties to change things about the post.
The Jekyll documentation at https://jekyllrb.com includes a list of all the front matter properties you can add and what they do. For blogs it can useful to add categories and tags to posts.
The tags and categories you use on your own site would just depend on your content. This means that categories can be used to organize the posts on your site into different sections.
At first, tags won’t show up anywhere, but many themes include a way to list all the posts in a particular tag.
Adding Pages and Static Content
Not all websites are blogs, and even blogs need some stand alone pages that aren’t blog posts.
Jekyll makes it easy to create these stand alone pages too.
For example, let’s say you want to make a page on my site for all your projects. You can run bundle exec jekyll page.
This will generate a new file called projects.md, not inside the posts folder, outside of it.
Jekyll also makes it easy to deal with other types of content, like images and style sheets.
Any other files or folders in this Jekyll project folder that aren’t recognized by Jekyll, simply get copied verbatim into the output folder.
For example, if you create a folder called images, and put some content in there, you can use it on various pages or posts.
When you’re working with content like images, sometimes this preview doesn’t update right away because of browser cache.
With the developer tools open (using the shortcut F12 or option+cmd+i), go to the network tab and then check “Disable Cache”. Now when you refresh, you will always see the latest version.
Error Pages
By default new Jekyll sites contain a file called 404.md. You can see it if you go to localhost:4000/404 in your browser.
Some web servers can be configured to point to this page whenever an error occurs or a page can’t be found. So visitors will see this page instead of a confusing error message.
You can customize this page to make it say whatever you want. Customizing the error page is totally optional but it can help add some additional polish to your site.
Site Generation
When you’re ready to deploy the site to the web, you’ll need to run a different command to tell Jekyll to generate the final site files. That command is bundle exec jekyll build instead of serve.
All of the site files are saved in an output folder called _site, or if you changed you configuration in a folder called public. This output folder contains folders and files for each one of your posts and pages.
Anything else you’ve added to your project, like files, style sheets, images, are also copied here. The contents of this output folder is the entire website. All you need to do is upload these files to a web server.
Publishing Options
Once you’ve built some pages and know how to generate the site’s content files, it’s time to explore getting your site on the internet. The HTML, CSS, and image files that makeup your site won’t do any good sitting on your computer.
To make your site public, you’ll need to put those files on a server that can host them for you. There are many ways you can do this. Since there’s nothing special about these files, you could manually copy them up to a web server. That works, but it gets old after a few updates.
First, there’s the FTP server approach. FTP is a common approach that’s used with many inexpensive web hosting companies.
If you already have access to a web server that supports FTP, use these instructions.
If you don’t already have a web server, I’ll show you how to publish your site using Amazon Web Services or AWS. This option costs only a few cents per month, but you do need to complete some configuration steps first.
The third option is to publish your site using a service built specifically for static sites called Netlify.
This is by far the easiest option and it’s the one you should start with if you’re not sure which one to pick.
There are a few things that you’ll need regardless of which deployment approach you choose.
You’ll use GitHub to store the site’s files for free and then set up another free service called Travis CI to run automated scripts every time you make a change. You’ll also need to grab a real domain name for your new site.