Few services have altered the way we build websites like GitHub Pages. The free hosting service that updates websites every time you commit changes to GitHub runs nearly all of our projects over the last two years, including some really big ones, like the United Nations Development Programme’s open data portal. It is fast, reliable, and has an incredibly easy workflow for development.

For those cases where we need the simplicity of GitHub Pages’ workflow but have to host on our own infrastructure, we built Jekyll-hook. It’s an extensible server that builds Jekyll sites on each commit to a GitHub repository, just like GitHub Pages. It provides a ton of additional flexibility, while preserving the benefits of static site generation, like needing no server-side processing to serve webpages.

Jekyll-hook is a Node.js server that receives web hook requests from GitHub.com, or a GitHub Enterprise server, generates a Jekyll site, and publishes it. The generation and publication processes are configurable with simple bash scripts. Get the full details at the Jekyll-hook project readme.

Why use Jekyll-hook?

For the majority of our projects, GitHub Pages works well. But there are some cases where additional needs drive us to build our own hosting environment:

• Use Jekyll plugins

• Publish directly to a CDN

• Host content behind authentication

Use Jekyll plugins

With GitHub Pages, Jekyll runs in safe mode, which means no third-party plugins will run. On a project like healthcare.gov, we encounter several simple problems that can be solved with small plugins that alter the way Jekyll builds the website. For instance, we just released the Jekyll Google Analytics plugin we’re using to download Google Analytics data and sort posts by popularity each time the new healthcare.gov website is rebuilt.

Using Jekyll-hook, you set up the Jekyll server, so you can run whatever plugins you want. Jekyll plugins introduce much lower risk than traditional CMS modules, because they run when the site is built, not when it is served. You can verify the plugin does what it should before your publish the website and not have to worry about plugins slowing down page load time.

In addition to Jekyll-ga, the new healthcare.gov uses plugins to generate a JSON-based content API, provide greater control to content administrators over post ordering and curation, and generate landing pages for blog post topics.

Publish directly to a CDN

For those cases where you need to be 100% certain of your website’s availability and responsiveness, we recommend using a content distribution network. For MapBox, we use Cloudfront, which is part of Amazon Web Services. For healthcare.gov, we’re planning to use Akamai. Both replicate content across a globally distributed network of servers to provide fast, reliable content delivery.

With Jekyll-hook, you write simple bash scripts to customize how your website is built where it is published. For the absolute best performance from your site, you would write a script that directly published your website to a cloud-based hosting environment like Amazon S3 or Akamai Net Storage and serve it through a CDN.

We’ve included a sample script that publishes Jekyll sites to Amazon S3. It works in the same way that GitHub Pages works, where repositories named *.github.com or *.github.io are hosted at the root of the S3 bucket, and other repositories for an owner or organization are hosted in subdirectories. If you use Jekyll-hook on new infrastructure, please contribute your publish scripts so we make it easy to people to use this server in a variety of hosting environments. We'll be working on an Akamai Net Storage script next.

Host content behind authentication

Occasionally, we’ll work on a project that needs to be protected by authentication, either because the data is private or during development of a yet-to-be released website. To make this easier, we’ve included a sample NGINX configuration and publish script so that Jekyll-hook can build sites to a simple web server with basic authentication. For the new healthcare.gov build, we’re using this on a micro EC2 server for a free / cheap development server that we can use to test and share the progress of our development.

Growing the CMS-free website stack

Just about nine months ago, we published our thoughts on building better websites by using Jekyll to generate static sites from content files and templates. By pairing this approach with APIs and embeds from services like Twitter, Disqus, Flickr, and Vimeo, we can build full-featured websites with absolutely no server-side processing when pages are viewed. It’s an incredibly scalable and versatile approach that we’re learning a lot about and expanding through our work with HHS on healthcare.gov.

About a year ago, to make editing static website simple for content writers, we built and released Prose — an open source web-based editor for Jekyll sites hosted on GitHub Pages. It’s a writers’ window into the powerful version control and collaboration features of GitHub. We’re just a few days away from releasing the first major version of Prose, which focuses on improving the usability and simplicity of editing content with a refreshed interface, metadata editor, and support for full in-layout previews.

Now we’re pushing the stack even further. In addition to the major upgrades to Prose, we recently shared how we’re providing multi-lingual translations for Jekyll sites, our approach to accessibility testing, and released the Jekyll Google Analytics plugin, bringing a whole new level of advanced features to Jekyll sites that previously required clunky content management systems.

Jekyll-hook is the latest piece of the puzzle. By removing the dependency on GitHub Pages for hosting, the CMS-free stack is becoming one of the most open and flexible way to build websites.

Cover photo by sbisson, CC BY-NC-ND 2.0.