Self-documented Makefile

Sunday, 02 November 2025 in London, GB

This isn’t a Make primer. Checkout https://makefiletutorial.com/ for that.

Here is my take on Make:

Every engineer needs to learn at least one build / task runner.
make ships with macOS, Linux by default, so no installations, make it great for adoption within a team.

The problem with make is you have to read the Makefile to understand what are the possible tasks. This template fixes that.

For example, the Makefile that I used for this blog is like this:

# Derived values (DO NOT TOUCH).
CURRENT_MAKEFILE_PATH := $(abspath $(lastword $(MAKEFILE_LIST)))
CURRENT_MAKEFILE_DIR := $(patsubst %/,%,$(dir $(CURRENT_MAKEFILE_PATH)))

.DEFAULT_GOAL := help
.PHONY: serve build new help

help:  # Display this help.
	@-+echo "Run make with one of the following targets:"
	@-+echo
	@-+grep -Eh "^[a-z-]+:.*#" $(CURRENT_MAKEFILE_PATH) | sed -E 's/^(.*:)(.*#+)(.*)/  \1 @@@ \3 /' | column -t -s "@@@"

serve: # Serve the server
	hugo server -D

build: # Build the site
	hugo

The usage is simple: add # comments to public targets, so when you run make you’ll see this self-documented doc.

❯❯ make
Run make with one of the following targets:

  help:          Display this help.
  serve:         Serve the server
  build:         Build the site
  new:           make new "your post title"

Having something like that in the team allows you to have straight to the point answers when people ask you on how to run things: