🍞 Makebakery

Michael F. Lamb

Thu, 28 Feb 2013 18:27:11 -0500

Makebakery is a static website generator implemented using GNU Make.

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

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 venerable old UNIX build tool intended for the compilation of software source code into executable code, but Makebakery puts it to use compiling websites. GNU Make is one popular variant of Make with several enhancements, included with most GNU/Linux distributions.

More accurately, Makebakery is a collection of rules and recipes for GNU Make that are useful for orchestrating various tools in the generation of static websites of varying architecture. Unlike minimalist Make-based approaches for generating static websites, Makebakery’s features are organized into modules which may be toggled according to the requirements of the site it is building.

Motivation

The basic idea of using Make to orchestrate building static HTML files from source files is fairly well-known. I’ve been doing it since I learned of the idea in 1998, after reading Using M4 to write HTML.

Unfortunately, I found myself re-implementing similar-but-different Makefiles over and over again for each different static site I wanted to build. Makebakery is the result of refactoring my various Makefiles into modular parts, and finding a simple mechanism to toggle those parts on or off for any site that uses the collection.

Example

A short Makefile is enough to get started:

SRC      = .
DST      = /tmp/build/example
MODULES  = ___ignore __source pandoc
IGNORE   = README.html Makefile
include /path/to/makebakery.mk

When you run make, this will copy source files from the current directory to the destination directory, and use Pandoc to convert Markdown to HTML in the process:

.                        /tmp/build/example
β”œβ”€β”€ about.md      ->     β”œβ”€β”€ about.html
β”œβ”€β”€ contact.md           β”œβ”€β”€ contact.html
β”œβ”€β”€ index.md             β”œβ”€β”€ index.html
β”œβ”€β”€ logo.png             β”œβ”€β”€ logo.png
β”œβ”€β”€ projects.md          └── projects.html
β”œβ”€β”€ Makefile
└── README.md

For a more detailed description, see the β€œminimal” example in the source code repository.

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. Adding a new conversion tool to this example is as simple as adding its module’s name to the MODULES variable, and defining any configuration variables it needs.

For a slightly more advanced example, examine Makefile and the associated source files used to build this site (that you are reading).


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.