Nowadays, there are so many options when it comes to developing a new static site. Which code editor should you use? How should you deploy your site? What is a static site generator? Here, I will walk through the setup that I ultimately chose to go with, and offer a couple of alternatives for those looking to build a site of their own.

Static Site Generators

Simply put, a static site generator is a web development tool which allows you to build webpages quickly, efficiently, and with little setup. Think of it as an intermediary between a fully coded site and a CMS, like WordPress. It provides enough flexibility to allow you to customize a site how you see fit without becoming too overwhelmed with tedious boilerplate code.

Is a static site generator right for me?

This can depend on many factors, as everyone’s requirements and desires for a site can differ. Personally, I was searching for a solution that would allow me to get up and running relatively quick, and would provide the functionality to create and edit content with ease. However, if you are looking to create content dynamically and have a desire to write server side code, then a static site generator may not be the correct solution for you.

Choosing the best solution

While there are many options to choose from when it comes to SSGs, the most popular (based on GitHub stars) are Hugo and Jekyll, so let’s compare:

Hugo is great if your goal is speed. Built with Google’s language Go, it renders fast page builds (think milliseconds) and has zero dependencies, making it a great choice for the performance seekers. There are plenty of resources online and has well written documentation to support new users. Content is created as either text files (Markdown), or just plain HTML. Hugo also makes use of Go’s html/template and text/template libraries. Talk about ease of development!

Jekyll is the right choice for those looking for a tight integration with GitHub Pages (it is the engine running behind the scenes). It was built by the founder of GitHub and has since become the most popular choice between the two (34.5k stars vs Hugo’s 26.3k at the time of writing). Jekyll allows you to easily migrate content from existing platforms, but can be a little more difficult to set up as it requires a Ruby installation and a RubyGems environment to get started. It is also slower at builds when compared to Hugo.

While both options come loaded with great features and themes to get you up and running, I decided to go with Hugo for performance and ease of installation reasons. If neither solution seems to float your boat, there are other site generators to choose from (see Hexo, Gatsby, or Pelican). Go with whatever suits your needs best!

Building a Site with Hugo

If you have chosen to build your site with Hugo, then the first step is to install it (assuming you already have Homebrew on macOS or Chocolatey on Windows):

macOS:

brew install hugo

Windows:

choco install hugo -confirm

Debian and Ubuntu:

sudo apt-get install hugo

Afterwards, you can build a new site with one command:

hugo new site <site-name>

This will create the folder structure necessary to get up and running with Hugo.

Adding a theme to your site

Once your new site has been created, you can add one of many themes from themes.gohugo.io and add it to your project with a few quick commands. Using the Casper Two theme as an example, you simply:

cd <site-name>;\
git init;\
git submodule add https://github.com/eueung/hugo-casper-two.git themes/casper-two;

The hugo new site command used earlier creates a config file which contains all of your site configuration. To let hugo know which theme to use, you must specify it in this file:

# config.TOML
theme = "casper-two"

# config.YAML
theme: casper-two

The config file is a central location where you will store most of your site metadata. To learn more about the Hugo config file, read about it in the docs.

Creating Content

Once you are ready to create new content, a simple command gets you going:

hugo new myAwesomeNewContent.md

Another great feature about Hugo is that it allows you to write both HTML and Markdown. This allows for rapid content creation while providing the option of coding custom HTML, if necessary.

You will notice that at the top of every new content page, there will be a code snippet:

title: My Awesome New Content
draft: true
description: Really great content waiting to be read.

This contains metadata about the content being created and can sometimes be specific to the theme you have chosen to use. Apart from this, the rest of the page is just plain old Markdown or HTML. To see the content you have just created, run:

hugo server -D

where the -D flag tells Hugo to serve the content you have labelled as a draft. Once you are satisfied with the content you have created, you can build the static pages with the Hugo command:

hugo

This creates a /public folder in the root directory and renders all Markdown content into HTMl, ready to be deployed to your host of choice.

Deploying your Hugo Site

They are many options when it comes to hosting a static site. GitHub Pages, AWS S3, Heroku, and Netlify are a among the most popular, but are certainly not your only options. For a small, static blog with an average amount of traffic, these options are well suited and all have free tiers to get you started (with the exception of AWS, which will run you a couple of cents per month).

Personally, I chose to go with Netlify for a couple of reasons:

  • It is free to use, so long as you stay within the tier limits.
  • Continuous deployment works out-of-the-box directly with your GitHub repository, and will auto-magically push your site to their global content delivery network.
  • You have the option of adding a custom domain name to your site, as Netlify includes a full featured DNS service.
  • There are lots of other great features, like access to AWS Lambda functions for serverless computing as well as built-in form handling.

Once you have signed up for a free account here and have gone through their setup, deploying your site is as easy as pushing your files to your GitHub repository. Then, sit back and enjoy a cup of tea as your site is deployed.

Pro Tip: Add an outgoing webhook (I recommend Slack) to receive notifications with the status of your deployment. This can be configured under Build & Deploy > Deploy notifications in the Netlify settings.

Bonus Points

If you would like to integrate your own content management system to avoid opening your code editor and editing the raw files whenever you wish to add content, I suggest checking out Forestry.io. It brings all of your content under an easy to use interface, speeding up your workflow and allowing you to publish new content at the push of a button!

That’s all for now! Keep hacking, friends!