Makefile-Based Static Website Generator

Photo: Boris Bartels, Bakery (2006) (CC-BY-SA 2.0). Resized.
Photo: Boris Bartels, “Bakery” (2006) (CC-BY-SA 2.0). Resized.

makebakery is a system of Makefiles that builds a static website from various sources, using the venerable old UNIX tool Make. Unlike typical Make-based approaches, its features are organized into modules which may be toggled according to your preferences.

A static website is one which requires no special logic on the server-side to work, as opposed to dynamic websites which trigger some server-side processing for most page requests.

Make is a tool that figures out which commands need to be run to transform some given set of source files into a desired set of output files. Originally created for compilation of source code into executable code, Makebakery uses Make to transform files in various source formats like Markdown into an HTML website.

I show in the demonstration site source code (which builds the site you are reading) how one might wire up their favorite HTML-generating tools to Makebakery. I recommend Pandoc, which lets you keep source files in Markdown format. You might also add to the compilation pipeline a template engine like Jinja, CSS compilers like LESS, image processing using ImageMagick, and any other custom scripts you please.

This website is the result of running make in the root of the makebakery source code directory, which compiles the included demo site source in /demo-src to HTML in /build/makebakery. Visit the makebakery project page on GitHub to learn more.

Interesting features

Static site generators are fairly boring, but there are some clever pieces within makebakery:

About static sites

Static websites are those whose content is pre-rendered and require only simple software to serve to visitors.

Static websites are useful because they’re effortlessly fast, scalable, and cache-able. Compared to dynamic sites, static sites are much easier to secure, and can be served from the very cheapest of hosting services.

This technique of pre-rendering static pages websites has been called baking a website, as opposed to a short-order server frying up each page upon each request.

Of course, with no processing occurring on the server end, it’s not possible to host user-interactive features like comments sections, authentication, or e-commerce systems. These days however, many people use third-party tools like Disqus to implement these features anyway, or rely on third-party forums like to provide discussion areas for their content.

In short, if you’re not using any of the dynamic features of your web hosting service, you might as well make the whole site static. If you are using those features on some areas of your site, you’re better off making the static parts simple static files.

If makebakery doesn’t meet your needs, it is only one of literally hundreds of different static site generators that people have made. A friend of mine wrote coleslaw and I’ve heard good things about Pelican too.

About Make

Modern Make work-alikes include Grunt, Rake, or Ant. Despite its age and the number of times it has been re-invented, Make has some surprising features that I think makes it superior to the newcomers:

Make has a rather steep learning curve, but since it is so ubiquitous, it’s likely to be already installed on your computer, and your web host’s servers, and easy to obtain if not.

Make is a POSIX standard, but makebakery relies on a specific implementation with non-standard features: GNU Make. Why?

… the POSIX standard version of Make is extraordinarily feature-poor; it lacks many basic functions that people need in practice. As a result, most people create makefiles (the input files to make) that require specific implementations instead of just following the POSIX standard. Typically that specific implementation is GNU make; since GNU make runs on nearly every Unix-like system, and is FLOSS, this is an easy requirement to meet.

–David Wheeler, Improving Make (2014)

More about Make and GNU Make: Wikipedia: Make (software)

Coming soon


Created by Michael F. Lamb. License: GNU Affero GPL version 3 or later, with additional permissions for output. See the COPYING in the source code for more information.