m4-bakery is a Makefile that builds a static website from various sources, using the venerable UNIX tools GNU make and optionally GNU m4. It is carefully crafted to be modular, allowing it to be customized to adapt 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 incur some processing overhead on the server-side for most page requests. 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.
GNU Make is a tool that takes as input a description of how compilation tools operate and a collection of files to be created, and figures out which commands need to be run, in what order, and on which source files, to compile those source files into their corresponding targets. When invoked multiple times it is smart enough to only recompile target files whose source files have changed. When used on multi-core systems or with I/O heavy jobs it is smart enough to figure out how to parallelize its work. Originally created for compilation of source code into executable code, I use to compile various source formats into an HTML website. Modern work-alikes include Grunt, Rake, or Ant. Despite its age and the number of times it has been re-invented, GNU Make has some surprising features that I think makes it superior to the newcomers.
GNU M4 is a macro processor which I employ as a minimalist templating engine. In the past, it formed the core of this software, but now thanks to a plug-in-style configuration for GNU Make, it is one of many template compilation options that may easily be toggled on or off. Perhaps this project should be renamed to make-bakery.
Both Make and M4 have a rather steep learning curve, but since they are so ubiquitous, it's likely that they're already installed on your computer, and your web host's servers.
I show in the demonstration site source code how one might wire up their favorite plain-text-to-html compiler to GNU Make. I recommend Pandoc, which lets you can keep all your source files in markdown format. You could similarly replace m4 with a modern templating engine like Jinja, or add CSS compilers like LESS, image processing using ImageMagick, and any other custom scripts you please to the compilation pipeline.
This website is the result of running
make in the
m4-bakery repository, which compiles the included demo site source to HTML.
The source code for this demo site is included with m4-bakery in the
demo-src directory. Visit the m4-bakery project page on GitHub to learn more.
Static page-compiling tools are fairly boring, but there are some clever pieces within m4-bakery:
demo-src/pages.json.m4.indexrenders a .json index of all the pages on the site. This enables us to automatically build navigation bars like the one in the header on this page, or "recent changes" links, all on the client side. Take careful note of this: the site is static but the header bar will automatically be rebuilt whenever pages are added or removed.
demo-src/atom.xml.m4.indexrenders an atom-format .xml file of changes made to the site. Even though the site is static you can still have it update feed readers whenever you make a change.