Under the hood of the new hackshackers.comSuggest edits
If you just want to know how to contribute code or text, check out the Hack This Site documentation. If you’re curious about the design process, we’ll cover that soon in another post. If you want to learn more about how the site works, read on.
In the CMS-driven sites that we’re all used to building and using, authors write content on one web page, which sends it to a server, which saves it to a row in the database. When someone’s browser requests a URL on the site, the server figures out which database row corresponds to the request, fetches it from the database, builds a HTML page, and sends it back to the browser. (This is an oversimplified version.)
Within this standard architecture, we could open-source the container’s code in a public GitHub repository. But that’s not feasible for the content; it needs the context of the server.
Thinking about opening up the content, our team at Alley Interactive started looking at static site generators. These are programs that translate static content files (usually Markdown) and templates to static HTML files that are uploaded to the site. Unlike the continuously running programs that power a CMS, the static site generator runs only when you need to compile a build.
Going back to that oversimplified explanation of a CMS, what actually happens when someone’s browser requests a URL is that they probably receive a cached version of the HTML page. This saves the server from rebuilding the same HTML page over and over, and improves performance.
With a static site generator, the cache is the whole site. It’s fast.
|Ease of setup||✔︎|
As the static site generator that powers GitHub Pages, Jekyll is by far the more popular. It has plenty of plugin hooks and clear documentation. Jekyll is very solid.
But it had two main drawbacks for our goal of making both the container and content user-editable. One, setting up a local Ruby environment could be a drag for anyone who wanted to tinker with the site. Two, Jekyll requires a file structure that makes it hard to wall content off from code.
Overall, Hugo’s easy setup and build speed convinced us that it was the better choice to help more people make more contributions to hackshackers.com.
Other (technical) stuff
In a standard Hugo setup, all the content source files live in the
content/ directory. This served us well, because we could make it an entirely separate repository included as a Git submodule of the main site. Hugo’s configuration also allowed us to place the data files inside the content repository, although our build script has to delete them before deploying the finished site.
Speaking of the build script, we used Wercker, a Docker-based service that integrates with GitHub. When there are new commits on the
master branch of the main repository, Wercker runs a fresh Hugo build and pushes the resulting files to Amazon S3. There’s a separate build script for new commits in the content submodule.
The map on the homepage and Groups page is generated using Leaflet.js and Hugo data files. Leaflet is pretty awesome and handled most everything we wanted to do by default. The only nonstandard feature is a custom button on mobile screens that toggles whether the map is draggable. This prevents it from capturing page scroll when you don’t want it to.
Finally, search can be the Achilles heel of static sites. But Lunr.js solved it for us quite easily. After each Hugo build, we rebuild a site index file. It takes a moment to load the index on the search page, but then each search takes only milliseconds.
Josh Kadis is the Director of Product Development for Alley Interactive, the digital team for publishers. Alley is proud to support Hacks/Hackers, OpenNews, and other organizations at the intersection of journalism and technology.