Static Site Generators

Chapter 4. Deploying a Static Site

Once you’ve built your static site using the generator of your choice, it’s time to share it with the world. The good news is that, because these are static files, there’s no complicated database deployment or environment to set up. Deploying a static site is simple.

This simplicity also opens up a huge number of options. In this chapter, we’ll look at just a few of the deployment and hosting options available to you for your static site.

FTP

Since you are dealing with static assets—typically just HTML, CSS, JavaScript, and images—deploying to just about any host via FTP requires no special setup. The only important thing to remember is that you need to build your site first; you do not upload the templates and Markdown.

Building Your Site

Some static site generators, like Jekyll, generate the site files whenever you preview the site. Nonetheless, it is best practice to do a build of the site before deploying. All of the static site generators have a build command of some form, often with some options. Let’s look at the process using the three generators we covered in the prior chapter.

In Jekyll, you’d use:

jekyll build

You can have Jekyll rebuild the site every time you make a change by adding -w to enable the watch option. For a full list of Jekyll build options, add --help.

In Wintersmith, you’d use:

wintersmith build

If you want to force Wintersmith to clear the output folder before building, use the -X option. For a full list of Wintersmith build options, add --help.

In Hugo, you’d use:

hugo

Hugo’s build process also includes the option to watch for changes with the -w option. For a full list of Hugo build options, add --help.

Assuming there were no errors, once you run the build process, your static files will be in the output directory that you set in your site configuration. But what happens if you do encounter an error?

Debugging

A majority of the debugging experience with static site generators is done via the console log within the terminal. This experience can differ with each generator and often depends on the underlying language or tools upon which the generator was built.

Some generators enable verbose logging in the console by default, and others do not. Verbose logging can be useful when trying to debug complex issues, but often it is extraneous information (see Figure 4-1).

Some generators will also give you error details when previewing a site in the browser; others fail silently in the browser but display errors in the console (see Figure 4-2).

The point is, there is no consistent debugging experience across static site generators, and the current experience often leaves much to be desired.

Figure 4-1. A Jekyll build error with verbose logging enabled. Jekyll does not provide verbose logging by default. To enable it, use the -v option when running a build.

Figure 4-2. Hugo displays error messages in the console but simply fails to display at all in the browser.

Once your site is built, open your FTP client, for example Filezilla or Transmit, and push the files to your host. One thing to remember is that some static site generators regenerate the entire site upon each build, so the sync feature available on many FTP clients will simply push the entire site, regardless. 

Glynn

Glynn is a tool that combines the build and deploy via FTP steps into a single command or Jekyll-based sites. To set up Glynn, you first need to install it via Ruby Gems:

gem install glynn --source http://gemcutter.org

Then configure it via your site’s _config.yml. There are a number of configuration options, but setting the host, root directory, and passive mode are the required options. In the following example configuration, username is included, meaning it will not have to be re-entered upon each use:

#glynn
ftp_host: 'your_site.com'
ftp_dir: 'site/root'
ftp_passive: true
ftp_username: 'your_username'

Once properly configured, enter the command glynn from the command line/terminal. Glynn will ask for your FTP password and, once entered, will push the files live.

GitHub Pages

GitHub and its free website hosting service, GitHub Pages, probably had a lot to do with the popularity of Jekyll. While technically GitHub Pages can host any static site, not necessarily ones created with Jekyll, there is close integration with Jekyll that makes it the de facto option. Let’s look at the how it works, since, in my opinion, the official documentation on Jekyll’s site makes it seem more complicated than it really is.

There are two types of GitHub pages: user/organization pages and project pages. It’s important to note that although we call these “pages,” they are actually full sites, not a single page. Let’s see how to create a user page.

First, go to GitHub and create a new repository. This repository must be named [username].github.io. For example, my username on GitHub is remotesynth, so my repository is named remotesynth.github.io. Next you’ll need to clone the new repository, either using the command-line Git client or the GitHub desktop app.

At this point, your repository is empty. Via the command line, change directory into the new repository and enter jekyll new ., which will create a new Jekyll site in the current directory. Open the _config.yml and modify the configuration with your correct site details.

Finally, just check the source of your Jekyll site into the GitHub repository. There’s no need to run a build (and the .gitignore file is set up to ignore the _site directory by default anyway, so don’t worry if you ran a preview). Your  new GitHub Pages user site should already be up and running at [username].github.io, albeit using the default Jekyll blog files.

GitHub Pages is an easy and free solution for sites such as a personal blog or a project blog. You can even set up a custom URL as opposed to using a github.io subdomain. GitHub offers additional documentation covering how to set everything up and run a Jekyll blog on GitHub Pages.

Surge

Another hosting option for static sites similar to GitHub Pages is Surge. Surge offers free publishing and custom domains on its basic account and more advanced options via a commercial offering. The benefit of Surge is that it makes the deployment process transparent via an easy-to-use command-line tool. It also offers integration options for various other build tools so that it can easily fit within an existing build and deployment process. Surge includes instructions for deploying Jekyll sites, but it will work with any static site generator.

Cloud Hosting

The list of cloud hosting options seems to grow every day, but any cloud host should easily be able to handle a static assets. Many of the popular static site generators include plug-ins, third-party tools, or direct integration for deploying to some of the more widely-used cloud hosting services like Amazon EC2, Heroku, Azure, and Modulus.

With the growth in popularity of static site generators though, some services have cropped up that offer cloud hosting services specifically targeting these tools. They offer some added conveniences that a traditional hosting service cannot because of their integration with the generators. Let’s look at a couple of options.

Netlify

Netlify is a commercial service that offers a cloud hosting solution specifically designed for static site generators. You can use their command-line tool to push static assets live. Even better, connect it to a GitHub or Bitbucket account and have it continuously build and deploy your application whenever new or updated files have been checked in.

The benefit of the latter option is that the build process occurs entirely on the Netlify servers. This means that there is no need to handle deployment of the static assets at all. Netlify pulls changes from the repository and updates the live site with the results of running the build command, which is configurable.

For example, I was able to get my personal blog, built with Jekyll, building and deploying on Netlify with only the addition of a Gemfile and Gemfile.lock. The gemfile only defined my Jekyll dependency:

source 'https://rubygems.org'
gem 'jekyll'

The Gemfile.lock will be automatically generated when you run bundle install after the Gemfile is created.

Once the files are committed to the repository, Netlify will automatically try to build the site and, if successful, it will immediately be available live.

CloudCannon

CloudCannon is a commercial cloud hosting service designed specifically for static sites built with Jekyll. The key difference between CloudCannon and the alternatives is that it offers a web-based user interface designed to allow nontechnical users to add or edit content on the site.

CloudCannon also integrates with repositories on GitHub or Bitbucket or even a specialized folder on Dropbox. This means that it will automatically sync and build changes to your site whenever they are checked in, eliminating the need for the build-and-deploy step.

Once the files are synced, they can be edited via the browser-based interface using a WYSIWYG-style editor for Markdown. For instance, Figure 4-3 is a screenshot of the editor that allows me to make modifications to my “About” page on my personal blog.

Figure 4-3. Modifying my “About” page using CloudCannon’s WYSIWYG editor for Markdown pages.

As you can see in the screenshot, CloudCannon even allows me to edit the Jekyll front matter using a form-based interface (on the right-hand side of the screen). There’s also a web-based editor for Jekyll collections.

The Possibilities Are (Almost) Endless

We’ve only managed to cover a handful of the many deployment possibilities available to you for your static site. Because we are dealing in purely static files, there aren’t the typical deployment limitations that may come with hosting a dynamic server-side language with a database server. A static site can be hosted just about anywhere, and usually extremely cheaply.

As I hope this and the previous chapters illustrate, however, is that static does not mean simple. Static site generators offer a lot of flexibility and power. You can build anything from a simple blog to a complex documentation site to a business website.

Yes, some of these tools can often seem obtuse and hard to use at times, especially depending on your level of comfort with the command line and Markdown, but, if you are able to overcome some of the initial hurdles in development, a static site can be remarkably easy to maintain, with the added benefits of speed, security, and simplicity.