Use a Static Site Generator to Build a Quick Website

Aaron Peters 12-03-2018

Welcome to the MakeUseOf Guide to Using a Static Site Generator. In this guide we’ll describe what a static site generator (SSG) is, why you’d want to use one, and how to build a brand new site with it. Some of the details we’ll explore:

This guide is available to download as a free PDF. Download Use a Static Site Generator to Build a Quick Website now. Feel free to copy and share this with your friends and family.

Table of Contents

  1. Introduction to Static Site Generators (SSGs)
    Why Should You Use An SSG? | How Do SSGs Work? | What Popular SSGs Are Available? | Selecting an SSG
  2. Preparing to Install Jekyll
    Advantages of a Local Install | Advantages of a Remote Install | Prerequisites
  3. Jekyll Installation
    Installing Ruby on Linux | Installing (Updated) Ruby on macOS | Installing Ruby on Windows | Installing Jekyll
  4. Project Setup and Structure
    Creating a Jekyll Project | Getting to Know the Jekyll Structure
  5. Jekyll Content Authoring
    Previewing Your Site | Updating the About Page | Updating the Site Configuration | Creating New Content in Markdown
  6. Building and Deployment
    Build | Deploy
  7. Jekyll Theming
  8. Jekyll Plugins

Introduction to Static Site Generators

The past several years have seen a resurgence in static websites. Many modern websites use a content management system Everything You Need to Know About Content Management Systems For the average internet surfer, viewing content is easy. You open a link, and the page appears. But what is taking place behind the scenes? Here's how your favorite CMSs take care of business. Read More  (CMS), which involves a combination of scripting and database content to build its pages dynamically.

In contrast, the pages for static sites are created, then uploaded to a web host. It sounds kind of old school, doesn’t it? Yes, but that’s a good thing.

Why Should You Use An SSG?

In the early days of the internet, web pages were created by crafting each page as a file, then uploading the files to a server. In today’s world of databases and fancy admin panels, this may seem a little dated. But a combination of two trends has led to the rising popularity of SSGs.

There are other benefits to SSGs 7 Reasons to Ditch Your CMS and Consider a Static Site Generator For many years, publishing a website was difficult for many users. CMSs like WordPress changed that, but they can still be confusing. Another alternative is a Static Site Generator. Read More , including the ability to work offline and a very fast site at the end of the day. Where static site generators don’t excel is in creating very interactive websites. If you plan to allow users sign up to comment on your site Should You Allow Comments on Your Site? The Pros and Cons Should you allow comments on your site or blog? On the one hand, you can argue that quality content will encourage quality comments; on the other, there's always someone out there with something negative to... Read More , or even create their own pages, an SSG may not be the best option. Likewise if you’re looking to sell products The 5 Best Ways to Create a Web Store We'll walk you through some big benefits and pitfalls of creating and running your own web store, and give you a head start on the road to digital entrepreneurship. Read More , allow users to message each other, or collaborate on documents. But if you’re looking for a simple way to get content in front of your audience, SSGs are a great option.


How Do SSGs Work?

Modern CMSes use a flow similar to the following:

  1. The site visitor requests a web page from the server.
  2. The server accepts the request and determines what the user is looking for.
  3. The server assembles the content using scripts which mainly query a database.
  4. The server sends the content back to the user in the form of a web page, which displays in the browser.

how cms work stack

In contrast, static sites forgo all that complexity by building pages beforehand. Then, a visitor’s browser simply asks for the page, and the server returns said page.

how cms work simple


Therefore, you can think of SSGs as essentially publishing tools. You create content, run an SSG, and it converts that content to web pages. You then upload those pages to a web server using any number of available methods.

static site generator

Sound good? If you’re intrigued, let’s take a look at some of the popular SSGs out there, and see what they’ve got to offer.

The website StaticGen is a leading resource for static site generators. It provides an extensive list of the ones available, as well as a ranking system based on user votes as well as Github forks What Is Git & Why You Should Use Version Control If You’re a Developer As web developers, a lot of the time we tend to work on local development sites then just upload everything when we’re done. This is fine when it’s just you and the changes are small,... Read More .


You can peruse the listing to easily see what programming language the SSG uses, and drill down to a summary of its features. Based on those listings, let’s examine some leading SSGs based on the below attributes.

This table summarizes the above for five leading SSGs:

static site generator compare table

Selecting an SSG

Like any application, you should select one of the available generators based on 1) how well it supports your needs and 2) some initial testing. Looking at the above table, three of its options jump out at me as good ones.


Jekyll is the most popular of them, and the most broadly supported in terms of available themes, plugins, etc. On the other hand, I like the greater content models in Hugo, as well as the possibility of using Org-Mode as an input. The ability to export a site as a PDF book via GitBook is also appealing.

Ultimately I’ve decided to go with Jekyll, as I can achieve some of its missing capabilities via plugins. But the deciding factor is that it’s written in Ruby, and web hosts are more likely to support Ruby than Hugo’s Go programming language. (“But wait, I thought this was a local program!” It is, or at least can be. As we’ll see in the next section, there are pros and cons to this.)

Preparing to Install Jekyll

Now that we’ve settled on Jekyll, let’s get everything set up. The following sections will help you decide where you want to install the generator itself, as well as what prerequisite software you’ll need.

Unlike a CMS, you have some flexibility as to where you install the static site generator application itself. Remember, these aren’t systems that actually serve the pages up to site visitors. They take content in one format and convert it to HTML. As a result, you can choose to install the SSG either:

  • Locally (i.e. on the same machine(s) where you’re authoring content)
  • Remotely (i.e. on the server where your site lives)

Advantages of a Local Install

The number one advantage of installing your SSG locally is the ability to easily preview before you publish. Your SSG is taking your plain-text content and spitting out HTML versions that have all sorts of visuals applied. It’s very useful to be able to build and preview your site in a browser (more on this later) before you worry about copying to a server. The below image shows the Hugo server running — note how it builds all the content, then starts a web server and provides you the URL to view it:

static site generator hugo serve2

As mentioned, a local install may be the only option available to you. Your web hosting environment may not support the base programming language One Size Doesn't Fit All: Why Software Isn't Universally Compatible Software is the same on any operating system, right? Wrong. It might look the same, and function similarly, but it is different behind the scenes. Read More  of the SSG. For example, without support for Ruby our Jekyll commands can’t run, and therefore you can’t build your site. You should have no problem installing prerequisites on your own machine however, unless you don’t have adminstrative rights How to Get Admin Rights on Windows Here's how to get administrator privileges on Windows 10 if your admin account isn't working for some reason. Read More .

Advantages of a Remote Install

On the other hand, you may choose to install the SSG on the server. In this case your workflow looks something like: 1) write raw content, 2) move raw content to server, and 3) run the SSG to convert raw content to HTML. Some of the benefits of this approach are as follows:

On one hand, the ability to preview the site before you publish any changes far outweighs the benefits of a remote install. So if you’re choosing just one, go for the local install.

But bear in mind though that the two aren’t mutually exclusive. There’s nothing preventing you from installing locally (e.g. on your Windows machine) for a normal “default” workflow, but also maintaining an install on your server for emergency posts from your mobile.


In order to make use of an SSG in general, you’ll need the following:

lightpaper two pane

If you’re the type of person who’s considering an SSG over one of the “point and click” site-building services 10 Ways To Create A Small And Simple Website Without The Overkill WordPress can be an overkill. As these other excellent services prove, WordPress is not the be all and end all of website creation. If you want simpler solutions, there's a variety to pick from. Read More , you likely have all these things already. In addition, you’ll need to meet software requirements. For Jekyll, these are:

  • Ruby version 2.2.5 or greater
  • RubyGems, a format for packaging Ruby-based applications
  • GCC and make, an open source software compiler (don’t worry, you won’t need to worry about this at all, but Jekyll does use it in the background)

Jekyll Installation

Installing Ruby on Linux

On Unix-based operating systems like Linux, prerequisites are a snap: a couple of simple command-line installs. On Ubuntu and its derivatives, the following APT command A Beginner's Guide to Installing Software in Ubuntu with APT If you've used Ubuntu you have probably used the apt command at some point. But did you know there's so much more to it than apt-get install and apt-get upgrade? Read More will get the Ruby language set up for you:

sudo apt install ruby ruby-dev

This will install the Ruby language as well as development tools, which are required to deal with some Gems. Gems are the Ruby package format, and installing some of them will actually build them in place. But don’t worry, the installers take care of all this.

Once Ruby is in place, you can install Jekyll as described in the “Installing Jekyll” section below.

Installing (Updated) Ruby on macOS

macOS does come with Ruby installed out of the box. Unfortunately, that version (at least as of High Sierra) is 2.0.0, and so is not sufficient to run Jekyll.

The most straightforward way to install is via the Homebrew project, which provides a command-line tool How to Install Mac Apps in Terminal Using Homebrew Did you know you can install Mac software in the Terminal? Here's how to use Homebrew to install Mac apps easily. Read More to install many useful open source programs. It’s not unlike MacPorts, which we’ve examined on MUO in the past MacPorts Brings the Best Open Source Software to Your Mac The Mac is an excellent host for many of the open source community's best free tools, and MacPorts is your "app store" for all this great software Read More .

First, get Homebrew base installed by pasting the following into the Terminal application. It will download and run an installer, which will further explain the process as it goes along:

/usr/bin/ruby -e "$(curl -fsSL"

static site generatore mac brew install2

Next, use the brew command to install an updated version of Ruby that will support Jekyll:

brew install ruby

At this point make sure you close and re-open Terminal — it will pick up the updated Ruby version (shown in the below image). Then do the install with the command in “Installing Jekyll” below.

static site generatore mac jekyll install1

Installing Ruby on Windows

Windows isn’t a formally supported target for Jekyll. Nevertheless, there are several ways to get it installed, some arguably less painful than the one for Macs.

static site generator ruby windows install1

Installing Jekyll

Once you have Ruby installed, you can use the gem command on all three platforms to install Jekyll and all its dependencies (around 25 in all):

gem install jekyll

Note: On Ubuntu, prepend the above with sudo to install system-wide. While a user-only install is possible, I found it to be problematic.

static site generator jekyll gem install1

Finally you can confirm Jekyll’s installation and version with the following:

jekyll -v

static site generator jekyll windows verify

If this worked, you can move onto the next section and get your first Jekyll site set up.

Project Setup and Structure

Creating a Jekyll Project

Now that you’ve got Jekyll installed, your first step will be to set up a project. This represents a single site you want to create and manage using Jekyll. The following command will create a new project in your current directory:

jekyll new awesome-site

This will create a new directory called awesome-site. Let’s dig in and familiarize ourselves with it.

Getting to Know the Jekyll Structure

The Jekyll project structure contains a number of key files and sub-directories, as follows:

  • _posts: As the name suggests, this is where you’ll place blog posts. Blog posts differ from “regular pages” in that they will contain a date that helps to sort them, as well as optional categories to organize them. In the Content Authoring section we’ll examine this more closely.
  • _config.yml: This is your site’s configuration file, written in YAML format. YAML is a markup language used for structured information, and is a common format for configs. We’ll change some of these when the time comes to start authoring our content.
  • 404.html: As with other systems, the 404 page displays when visitors request unknown URLs.
  • Gemfile: This is a Ruby configuration file. We’ll add to this later when installing additional components, but for right now don’t make any changes to this.
  • If you’re familiar with web servers in general, this should look familiar. When a user goes to a URL (like “”), a typical web server will attempt to load up either “index.html” or “index.php.” This Markdown file will be converted into the “index.html” of our static site.

You may notice one thing missing from this list… pages! How can you have a site without pages?

static site generator jekyll file manager

You’re free to create other files and folders for your site. As long as they don’t start with an underscore they’ll be considered “content folders.” You can place these “raw” source files either in the root of your project (such as the “” file shown in the above image) or in these arbitrary folders. All that’s missing is for us to actually write some content. We’ll buckle down in the next section and do just that.

Jekyll Content Authoring

Previewing Your Site

The first thing we can do is to see how the site looks out of the box. As discussed, one of the advantages of installing Jekyll locally is using its built-in web server to easily preview our site. The following command will start that server, and let you know how to point your browser to it.

Note: It is important to issue Jekyll’s commands from your project’s directory (i.e. “/home/aaron/Documents/awesome-site/” in the below example). Otherwise you’ll get all sorts of errors about missing things that only seem that way because you’re not in the right place.

static site generator jekyll serve

As the output says, we can open this up now in a browser using And now there’s a site welcoming us to Jekyll, as shown in the below image.

static site generator jekyll index update

Updating the About Page

From the above image, we can see an “About” link in the header menu. Clicking that brings up a page with a bunch of junk about Jekyll and its Minima theme.

static site generator jekyll about1

But this is my site! Let’s change this to personalize it. We can add some Markdown to the “” file in the root of our project. Note also the “front matter” at the top of the file, where the “/about/” URL is specified.

static site generator jekyll about2

Refreshing our browser tab (Jekyll’s server will pick up our changes in real time), our welcome message appears right there at the top. Perfect!

static site generator jekyll about3

But now other things become noticable. The site’s title is “Your awesome title” instead of “My awesome title.” And there’s some nonsense about “_config.yml” in the site’s description. Let’s fix them.

Updating the Site Configuration

The _config.yml (it’s actually important and not nonsense) file holds some important information about our site, as shown in the below image:

static site generator jekyll config

Finding and adjusting things are straightforward here, let’s 1) change the title, 2) change the description, and 3) remove the Github link. Unlike the page changes, we’ll need to restart the server to pick up the updated config file with Ctrl + C (to stop) and jekyll serve (to start it again):

static site generator jekyll index update2

But fiddling with YAML isn’t what we were going for. No, we want the ability to create content in formats like Markdown.

Creating New Content in Markdown

As mentioned earlier in this guide, the way to create content for most static site generators is in Markdown. This very popular lightweight markup language makes it easy to create web pages in a text editor. We’ve covered it a number of times before on MUO, including the reason’s it’s worth learning What Is Markdown? 4 Reasons Why You Should Learn It Now Tired of HTML and WYSIWYG editors? Then Markdown is the answer for you no matter who you are. Read More , and solid editors for Windows 5 Sites and Apps for Quickly Learning Markdown Markdown is the default writing format for many. Get used to it with some tools that help you learn, and then use, Markdown. Read More , Mac, and Linux Looking For A Markdown Editor For Linux? Try These 3 Solid Options Windows and Mac users have many Markdown editors to choose from, Linux users, less so. Here are some choices. Read More . But if you’re completely new to Markdown, Michael’s super Markdown overview Learning Markdown: Write For The Web, Faster Markdown is the best way to write in plain text but still create complex documents. Unlike HTML or LaTex, for example, Markdown is simple to learn. Read More should be your first stop to learn the ins and outs.

Once you’re comfortable putting some Markdown together, we can move on to creating your first post. Create a new plain text file with the name “” via whatever method you like, where the first part of the name represents the date. Place the file in the “_posts” directory, then open it with your favorite text editor.

Raw Jekyll source files are mostly standard Markdown, with the exception of the front matter. This is some configuration that appears at the beginning of of the file in YAML format (see, told you it was popular). The most basic thing you can provide via front matter is the post’s title. You should also select one of your theme’s available layouts (“post” in the below example). Place these into your Markdown file at the very beginning between two sets of three dashes:

title: "Testing Out Some Headings"
layout: post

After closing the front matter with three dashes, you can write the remainder of the content in standard Markdown. It’s best not to use any H1 tags directly, because Jekyll will apply those to the title you’ve defined above. But adding some lower headings (second- and third-level) and other text (including a bulleted list) gives us a fairly fleshed out page.

static site generator jekyll post

At this point, you can begin accumulating posts. If all you want from your Jekyll site is a simple, journal-style blog, well, you’ve got it. Some further steps you might want to consider taking include (the links will take you to resources with more detail):

  • Creating other static pages like the “About” page we revised earlier. Remember, you can put the source files for these either in the root of the project, or in sub-folders you define.
  • Categorizing pages in the front matter with the “category” keyword. Then, create landing pages that filter each of your categories.
  • Organize the pages into a site tree using the “permalink” keyword in the front matter. This allows you to, for example, specify that the “” in the root of your project actually gets an address of “ /about/“.

With this knowledge in hand, you have everything you need to create a website to serve as a portfolio, personal blog, or even a small business site. The problem is, up until now, it’s still confined to your desktop. In the next section we’ll explore what happened when you built your site (you didn’t even know you did that, did you?). We’ll also look at some methods to get the built, or “generated” site, onto the web.

Building and Deployment


static site generator jekyll build

Take a peek at the above screenshot — on the fifth line you’ll notice the output “Generating…”

In order to serve your site, Jekyll first needs to build it. This entails converting all the Markdown to HTML How to Easily Convert Between Document Formats in Linux Switching to Linux can result in problems with file compatibility. For instance, documents don't look the same in LibreOffice as they do in Word. This is just one reason why you need pandoc. Read More , and assembling pages as required (such as the category pages we mentioned earlier). The jekyll serve command also builds the project for you. This is why we’ve only had to refresh our browser to see changes.

We can also build the project manually with the following command:

jekyll build

Building your project creates a sub-directory called _site. It contains the “live” version of your site (we’ll discuss how to do this in the next section). It contains a structure similar to, but slightly different than, the main project structure:

static site generator jekyll build2

In the course of building the project Jekyll will take steps including:

  • Converting Markdown to HTML.
  • Adding “included” elements, such as headers and footers, to the pages of the site.
  • Replacing dynamic snippets in the templates with their values. An example is creating a page by looking for all blog posts and filling a list with their dates and titles.
  • Creating navigational where necessary, such as the folders for post categories (“jekyll” in the above image) or a menu entry for the “About” pointing to “ /about/“.

At the end of this process, you’re able to simply push the contents of the “_site” directory to a web hosting environment.


The sites generated by Jekyll don’t require any fancy database installation to work. All you need to do is get all the content of the “_site” directory onto your web host. There’s a number of methods you could use to do this, including:

At this point, you have everything you need to create a website. But that’s not to say we’ve covered everything. For instance, the default Minima theme is a little, well… lacking. Let’s jazz it up with something a little sharper.

Jekyll Theming

The most difficult thing about getting a new theme for your Jekyll site is choosing from among all the options. There are hundreds available. Try the Jekyll Themes site for a nice, browsable gallery of themes. Once you decide on one, follow the instructions on its website to install it.

static site generator jekyll themes

Note: Many themes are packaged as Ruby gems, which means you can take advantage of the “gem install” command we used earlier. However this is still a work in progress. Alternately, some themes may have you install manually.

Since big, vertical sidebar menus are cool, we’ll install the Hydeout theme. (You’ll find many references to the classic novel throughout the Jekyll ecosystem.) It’s packaged as a Ruby gem, so you can install it using the same command we used to install Jekyll in the first place:

gem install jekyll-theme-hydeout

Then create a new Jekyll site, and change the following two to 1) take into account the gem containing the theme, and 2) actually apply the theme to the current site. First, change the following line in the Gemfile:

static site generator jekyll theme1

Now, change the setting in _config.yml to use Hydeout (using the gem name, “jekyll-theme-hydeout”) signifying the site’s active theme:

static site generator jekyll theme2

Now re-start the Jekyll server (remember, we touched the config file), and see your awesome new theme:

static site generator jekyll theme3

Jekyll Plugins

Themes aren’t the only way you can spruce up your site. Jekyll plugins help to add functionality ranging from new input and output options, auto-generation of tables of contents, or embedding a Spotify web player 7 Reasons to Start Using the Spotify Web Player Today Spotify is about to shake things up by making the desktop and web app experiences more similar. So, it's about time many of us asked ourselves, Why not just use the web app instead? Read More . It can even provide some of the functions that we’d highlighted as disadvantages of SSGs, like comments (e.g. the gem “disqus-for-jekyll” enables the Disqus service).

We’ll install an administration panel for our site, making it into something like a “static site CMS.” The “jekyll-admin” gem has this functionality… all we need to do is install it:

gem install jekyll-admin

And then enable it in our Gemfile according to the developers instructions:

static site generator jekyll admin

Done! Go to your site’s new administration panel at yoursite:4080/admin:

static site generator jekyll admin2


To recap, in this guide we’ve learned:

  • How SSGs take plain text content and transform it into nicely-formatted web pages
  • What the important attributes of SSGs are, and how to select one that works for you
  • How to install the Jekyll static site generator on Windows, Mac, and Linux
  • How to start your first Jekyll project, and what its structure looks like
  • How to create content for your site using the Markdown language, and preview the results
  • How to take the output of Jekyll and get it from your local machine to a web host
  • How to install and select a new Jekyll theme for your site
  • How to install and use add-ons to add functionality to Jekyll

Armed with this knowledge, you should be able to use Jekyll to get a basic, content-centric website running quickly and easily. Furthermore, that site will be fast, secure, and easy to manage. You can work on your content wherever you are, whether you have internet access or not, and preview your work just as if you were online.

You can host your site on just about any web host, even using very affordable and “bare bones” plans. At the same time, you can use modern, great-looking themes, and even add some of those CMS features through plugins.

What do you think of SSG-based sites? Is it right for you? Or does it all sound too complicated, and you’d rather just stick with WordPress? Let us know in the comments!

Related topics: Blogging, Longform Guide, Web Development.

Affiliate Disclosure: By buying the products we recommend, you help keep the site alive. Read more.

Whatsapp Pinterest

Leave a Reply

Your email address will not be published. Required fields are marked *

  1. Don
    April 6, 2018 at 5:22 pm

    Thanks for a thorough how-to guide also covering multi platforms. A well-done introduction to get Jekyll working.