Troubleshooting GitHub Pages Jekyll "Page Build Failed" Error

AKA “We’re not rebuilding your site and we’re not telling you why”

This site is hosted on GitHub Pages, an excellent free service that runs on Jekyll.

I recently pushed an update to change the permalink structure and got an email with a generic “page build failed” error, with a completely unhelpful link to GitHub’s documentation. After some Googling I was still stuck so by trial and error I undid various changes and re-committed until the site built OK again.

The issue? I had a commented out line in my _config.yml:

name: ctrl.alt.rees
# permalink: /:year-:month-:day-:url.html
permalink: /:year-:month-:day-:slug.html
highlighter: rouge
google_analytics: UA-71346066-3
url: "https://ctrl-alt-rees.com" # Base URL for sitemap generation
plugins:
- jekyll-sitemap

For some reason Jekyll will happily build this locally but GitHub Pages doesn’t like it - despite the fact that it seems perfectly happy with the other comment further down the same file.

Answers on a postcard, please.